py_guide package

Module contents

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)

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

• Define the argument in the parser_build() method
• Create a route_action_[description] method following the existing pattern
• Call that method within route_arguments() for the correct condition

Note:

Using the main() will help creating deployment packages using setup.py, wheel, and wanting creation of any entry point in the scripts directory of the virtual environment

When an argument is parsed it should be routed to a handler action method.

py_guide.__main__.parser_build()

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)

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.__main__.route_action_show_menu(cmdline_parser)

If --show_menu is passed as part of calling this module, this method will be triggered by routing, and a console menu will be shown.

py_guide.__main__.route_action_version()

Will display the version of the current package.

py_guide.__main__.route_arguments(cmdline_parser)

This method will use the arguments parsed from the command line to route different pieces of functionality in the module

Submodules

py_guide.console_menu module

class py_guide.console_menu.ConsoleMenu(cmdline_argument_parser, logger=None)

Bases: object

close_menu()

create_virtual_environment(venv_path)

log

make_directory(directory_name)

new_project_generator()

Collects some information, then generates a project using the best practices of this guide.

static pause()

show_help()

show_menu()

py_guide.log_4_trees module

class py_guide.logging_trees.LoggerOfTrees(allow_log_file=True)

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()

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')

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

static make_directory_log_file(self, directory=None)

Create directory on the local file system for the log file

py_guide.project_factory module

This file will create an instance of a new project with default settings

class py_guide.project_factory.PyProject(logger=None, project_name='python_project')

Bases: object

author

create()

Create a template project on disk from the information in the object

create_console_menu(environment=None)

create_core_files()

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.

Note:

The environment parameter for each sub-method will give it the context of loading templates with py_template sub-package as the root. In contrast, when you write a file, it will be written relative to the project root.

create_dist_pypi(environment=None)

Creates the distribute to PyPi bat files for Windows machines.

Args:

environment(Jinja2.environment): Context for the template engine Jinja2

create_docs_source(environment=None)

Creates the Sphinx configuration file in the docs_source directory

Args:

environment(Jinja2.environment): Context for the template engine Jinja2

create_gitignore(environment=None)

Creates the GIT Ignore file. This list excludes things in the project that should not be checked into source control.

Args:

environment(Jinja2.environment): Context for the template engine Jinja2

create_init(environment=None, directory=None)

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.

Args:

environment(Jinja2.environment): Context for the template engine Jinja2 directory(str): A string that can be treated like a PathLike object

create_jrepl(environment=None)

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)

Creates the LICENSE file for the project.

Args:

environment(Jinja2.environment): Context for the template engine Jinja2

create_logging(environment=None)

create_main(environment=None)

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)

Creates the LICENSE file for the project.

Args:

environment(Jinja2.environment): Context for the template engine Jinja2

create_project_directories(project_name)

create_readme(environment=None)

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.

Note:

I have recently discovered that if you use BitBucket Server (installed, not cloud) they will not render rst files. May need to consider changing the README.rst to README.md in that circumstance.

create_requirements(environment=None)

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.

Args:

environment(jinja2.Environment): Context for the template engine Jinja2.

https://jinja.palletsprojects.com/en/2.10.x/api/#jinja2.Environment

create_run_configurations(environment=None)

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.

TODO:

Extend this project to have a run.py or build.py or some structure like that which will allow build without PyCharm

create_setup(environment=None)

Creates the setup.py file for the project used with building the wheel file, deployed via pip

description

find_project_base_directory()

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)

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()

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={})

Wrapper method for successive file creation. Assumes all files want to be written relative to the project root.

Args:

file_name(str): Name of the file to write template(jinja2.Template): The jinja2 template to be written template_data(dictionary): Key/Value pairs of data for the jinja2 template