DocStrings in an __init__ file will be written to the Module Contents section of auto-code documentation generated by Sphinx. In our guide we also list the module contents before the submodule. This is not the default but can be generated with autodoc using the –module-first option. Or, of course, you can also manually edit the rst file for the module.
py_guide.__main__.main(args=None)[source]¶As a best practice, main() will be the entry point for this package. We will define a pattern of how we take information passed to main (arguments) and send them to methods to handle them (route). First we will define an argument parser. We put it in it’s own method to keep the main method clean. Next we’ll use a route_arguments() method, which in turn will handle further routing delegation via other methods, as a way to handle command line parameters.
If you want to add an argument
When an argument is parsed it should be routed to a handler action method.
py_guide.__main__.parser_build()[source]¶This method builds the argument parser to handle values passed in from the command line. Centralized in this method for readability.
The Argument parser allows standard patterns for parsing. For instance you do not have to program -h, or –help to explain how the command line is used. The argument parser will build this from the arguments, and descriptions provided for those arguments, when building the parser object.
py_guide.__main__.route_action_list_of_strings(args)[source]¶If a list of strings is passed as a command line parameter, this method will be triggered by routing, and will handle that argument. At this time we will simply echo back the values passed in, as the point is to show how argument parsing works.
py_guide.logging_trees.LoggerOfTrees(allow_log_file=True)[source]¶Bases: logging.Logger
Great Software has Great Logging.
https://www.google.com/search?q=logging
log·ging noun /ˈlôɡiNG,ˈläɡiNG/
the activity or business of felling trees and cutting and preparing the timber.
Originally created to deal with writing log files to directories (and creating that directory etc), I encapsulated the Python standard logging into my logging_trees project. By default this class can create the logging file and add the handler to direct logs to it. The file logger will be set to write all logs to the file. In addition we the logger will take Info level logs and above, and also write them to stdout so that it can be used instead of print statements.
add_handler_file()[source]¶This method could have been called create log file. It will create a logging “handler” which is the Python term for where to write the log. It’s cool because logging can have more than one handler. Such as by default with this class, there is all a handler to put things to stdout like a print() statement.
add_handler_stdout(msg_format='%(levelname)s | %(message)s')[source]¶This method could have been called send logs to stdout like a print() statement. It will create a logging “handler” which is the Python term for where to write the log. It’s cool because logging can have more than one handler. Such as by default with this class, there is all a handler to write logs to a file
allow_log_file¶Property create_log_file is True if we want to write a log file. Originally for containers this flag was add for those cases where we don’t want a file log. Normally we still log to standard out.
log_directory¶This file will create an instance of a new project with default settings
py_guide.project_factory.PyProject(logger=None, project_name='python_project')[source]¶Bases: object
author¶create_core_files()[source]¶Creates standard files for all projects following this Python guide. As a pattern this method will call another method to create the file. In that method it will handle the data needed for that file, as well as calling another method to write the file.
create_dist_pypi(environment=None)[source]¶Creates the distribute to PyPi bat files for Windows machines.
create_docs_source(environment=None)[source]¶Creates the Sphinx configuration file in the docs_source directory
create_gitignore(environment=None)[source]¶Creates the GIT Ignore file. This list excludes things in the project that should not be checked into source control.
create_init(environment=None, directory=None)[source]¶Creates a Python __init__ file. As this file can be used multiple times within packages and sub-packages, we will allow for a directory parameter on where it should be written.
create_jrepl(environment=None)[source]¶jrepl.bat or jreplace is a batch script that will update another file. On a windows box it can be used to update the project.cfg file with builds.
create_license(environment=None)[source]¶Creates the LICENSE file for the project.
create_main(environment=None)[source]¶Method creates the __main__ file for the project. As part of our best practices standard the __main__ is important for creating a standard handling of arguments with argparse, a standard way to route those arguments to methods to implement them, and a standard way to create entry points. Entry points enable an installed application to have a Scripts/ directory start command. For instance, when this project is installed, there is a venv/scripts/py_guide command that can be executed.
create_project_config(environment=None)[source]¶Creates the LICENSE file for the project.
create_readme(environment=None)[source]¶This method will create a README.rst file. We use rst so that it will be displayed in Rich Text when using systems like github.
create_requirements(environment=None)[source]¶Creates the requirements.txt file. This file is used by Python to update a projects virtual environment with the packages needed to run the project. Initialized with core packages that are needed for all projects like pip, setuptools and wheel, and packages needed to follow good practices like documentation, such as sphinx.
create_run_configurations(environment=None)[source]¶This method creates files that allow for building of the project. Originally conceived to create the PyCharm .idea/runConfigurations xml files. I’m a big fan of PyCharm and recommend that if you are writing Python get the community edition. When you’re good enough to know why it’s worth it, by a pro license.
create_setup(environment=None)[source]¶Creates the setup.py file for the project used with building the wheel file, deployed via pip
description¶find_project_base_directory()[source]¶Determines a directory for creating the new project. First check to see if there is a PycharmProjects directory in use. If so use it. If not then just use the user directory.
log¶make_directory(directory_path=None)[source]¶Creates a directory for the project. Handles errors and logging
name¶This is the name of the project and the root of the directory structure.
project_absolute_path¶The abspath() of this file. The absolute path will be the full file on path on disk for the operating system you are on.
project_directory¶project_name¶remove_directory()[source]¶Primarily created for when make_directory experiences a FileExistsError, this method will delete an existing project folder. It takes the name we pass (or wnated to create) and finds it in the project directory path. This allows the calling user interface to not have to understand the full path to the directory.
write_file(file_name=None, template=None, template_data={})[source]¶Wrapper method for successive file creation. Assumes all files want to be written relative to the project root.