Application With Internal Packages
00:00 I started with a single-file application. In the previous lesson, I advanced that to multiple files in a module. In this lesson, I’ll show you what changes when you start adding multiple modules, and I’ll give you a tour of one tool that you can use to help you with your documentation. In a larger application, you’re probably going to use multiple modules.
This becomes particularly important if you’re doing a GUI. Oftentimes when you structure a desktop GUI application, you’ll have modules for the UI and separate modules for the business logic, so this kind of multiple-modules setup becomes more important with that kind of application. So, some things that might change: You may add a
bin/ directory is where your executables for the user actually run. These are usually just thin wrappers to the entry points inside of your modules.
data/ directories: if you have data for your tests or data for your application, you want that separate from your actual code.
00:51 And of course, the bigger your application gets, the more likely you’re going to need documentation. Your users will appreciate it. The changes here aren’t really drastic; there’s just more nesting.
helloworld/ becomes a root place with multiple modules: a
hello/ and a
world/ inside of it.
world/ have a similar structure to the
helloworld/ in the previous lesson. You’ve got your
__init__, you’ve got some files—these are our modules. Of course, the same kinds of structure happens inside of
You want your test structure to more or less map to the module structure for the tests going with it. On the right-hand side, as I mentioned before, a
bin/ directory is a good place for your entry point, so now I’ve got a program that is actually called
helloworld, which would be what the user actually runs. A
data/ directory, and then somewhere to put the docs, and the grayed-out stuff I discussed in the previous lesson. The
bin/ directory: this holds the programs the user will execute. Typically, you drop the
.py ending here because if you’re building a larger application, you’re probably focusing it on someone who isn’t actually a Python programmer and isn’t thinking about
.py. They just want to run a program, so you name it the way you would name a program on your operating system.
There should be very little code logic inside of these. Typically, they’re just wrappers for your main modules’ entry points. This keeps them nice and clean. Finally, you can configure
setup.py to actually point to this script so that when your module or wheel gets installed, the scripts in the
bin/ directory can be put on the user’s path, making it easier for them to execute.
data/ directories are for data; if your program’s got files that it needs to load to get things done—either for testing or for the program itself—it goes here.
02:28 This is really just a way of trying to keep things clean and keeping your data separate from your application. You can also put sub-directories inside of this folder if you want to separate production test data or any other sort of organizational hierarchy that makes sense for your application. As your application grows, the more important documentation becomes.
02:47 This is an often overlooked part of your package, but for it to be useful to users, they need to be able to know how to use it.
I typically use Sphinx to do my documentation. It’s based on the RST format, and it interacts with your
pydoc comments so you can pull documentation out of your actual code.
Sphinx is available as a
pip module, so you do your typical
pip install. If you’re using Read the Docs to host your documentation, you can also install the Sphinx Read the Docs theme so everything looks like Read the Docs.
There’s a quickstart script that comes with Sphinx that helps you set up your configuration, and then once you’ve got everything going,
make html is how you actually build your documentation. This is an example of the Read the Docs theme for the Hello World application that I’ve been showing you.
As you can see, nice and clean, a built-in search mechanism, links to the different modules. Simple, easy to use, easy to understand. Okay, so this is me inside of my
sphinx-quickstart script creates the
conf, and the
make.bat file for you, as well as a basic
world.rst I’ve added with some information for the application. Up until now, I’ve been using Markdown for the
README file. Because I’m using Sphinx here and Sphinx uses RST, I’ve actually changed the
README file in the directory above to be an RST file.
04:16 They’re similar formats—it’s not a big difference.
index.rst file is the landing page. I’ve included the
README.rst up top. This allows me to use the
README file twice—it needs to be in the root directory for GitHub to see it for the GitHub homepage, and I can include it here so that I don’t have to rewrite the main description for the project. The pipe here says to include the version number, which is inside of
This is then a table of contents and it is importing
world.rst, which I’ll show you in a second. Finally, it generates indexes and allows you to plug in
04:54 Most of this file is created for you by the quickstart, so you just need to add a tiny bit.
Now, I’ll show you
You can write whatever makes sense to describe this module for you. You can also take advantage of the
automodule mechanism. This reads the docstrings out of
helloworld.hello.hello and includes that information inside of the result.
I then do the same for the
world.rst is similar to this file. By structuring it this way I can build out documentation for each one of my modules and then have it all tied together as part of
and Sphinx generates all of the documentation. At the bottom here, you’ll see the results are in
_build/html. Sphinx allows you to also output to things like LaTeX and other formats, so if you want to do more than HTML, you can do that as well. So once again, here’s the result. This is the page produced by
If you click on the link to the
hello module you get
hello.rst. This is the text from
hello.rst, and these are the
automodule statements pulled out of the code itself. Using the
pydoc means you can keep your documentation with your code, which improves the likelihood that it’ll get adjusted when your code changes.
06:14 So, that was a multi-module application and the documentation to go with it. Next up, I’ll show you what a Django web application looks like.
Become a Member to join the conversation.