cc-pyscript sample repo

This is a sample repository generated using the cc-pyscript v0.1.0 cookiecutter template, which can be found here: https://github.com/sedelmeyer/cc-pyscript

https://github.com/sedelmeyer/cc-pyscript-sample-repo/workflows/build/badge.svg?branch=master

Summary

Todo

  • Add a brief summary of this project.

The cc_pyscript_sample_repo.py script itself can be found in the src/cc_pyscript_sample_repo/ sub-directory.

Command line usage

To invoke this Python script, simply run python cc_pyscript_sample_repo.py.

Additionally, this script can also be run from the CLI entry-point cc-pyscript-sample-repo if the overarching cc_pyscript_sample_repo python application (i.e. package) is installed locally.

Running the script’s --help command with python cc_pyscript_sample_repo.py -h will provide the following usage intructions:

ADD STDOUT USAGE INSTRUCTIONS AS THEY APPEAR IN THE TERMINAL

Todo

  • Add stdout usage instructions to the code block above.

Getting started

0. Ensure system requirements are met

The requirements for executing this script are:

  • Python>=3.7

    • Python=3.6 will also likely work, but has not been tested.

    • Only the Python Standard Library is required.

Additional requirements for developing and testing this script, or installing the tech_grant package locally for running the CLI download-files entry-point directly are:

  • pipenv

    • pipenv, version 2020.8.13 was used for developing this script, however older versions of pipenv will likely work.

    • If you prefer NOT to use pipenv for packaging and virtual environment management in favor of an alternative such as conda or virtualenv, you will need to modify the project repository and .tox test matrix accordingly.

1. Clone this repository locally

The src/cc_pyscript_sample_repo/cc_pyscript_sample_repo.py script can be used as a standalone document, therefore, the rest of the files included in this project repository are not technically required for its use. However, for development and testing of this script, it is recommended that the entire project repository be cloned locally from GitHub. This repository can be cloned with the following command:

git clone https://github.com/sedelmeyer/cc-pyscript-sample-repo.git

2. Install the required environment using Pipenv

If you are new to using Pipenv for managing your working environments, please take some time to familiarize yourself with the tool. The official Pipenv documentation is a good place to start.

To install your Python dependencies directly from the deterministic build specified by the Pipfile.lock, simply run:

pipenv install --dev

Once your pipenv environment is built, you can enter it with:

pipenv shell

As noted above in the requirements section, Pipenv is used to manage development requirements for this project. Pipenv is not necessarily required for just executing the script, because the script requires only the Python Standard Library to execute successfully.

Troubleshooting: It is possible that the frozen requirements specified in the Pipfile.lock may cause errors on some operating systems due to varying system-specific requirements needed to install pytest and some other development requirements. If you encounter this error, you may wish to delete your local version of the Pipfile.lock file and re-run pipenv install --dev.

Adding to this project

If you’d like clone and build off of this project, below are some important notes regarding the configuration of this project.

Todo

  • Below are placeholder sections for explaining important characteristics of this project’s configuration.

  • This section should contain all details required for someone else to easily begin adding additional development and analyses to this project.

Project repository directory structure, design, and usage

The repository structure, packaging, and workflows for this project are largely based on the conventions used in the cc-pyscript Cookiecutter template available here. Please read the documentation for that project for a complete overview of the tools and conventions used in the cc-pyscript-sample-repo project.

Python package configuration

This package is configured via the setup.py and setup.cfg files found in this repository. The source code for this package is located in the src/cc_pyscript_sample_repo/ directory. For general information on the benefits to this approach for packaging a Python library, please see this article.

Testing

This project is configured for automated testing using tox and continuous integration services via GitHub Actions. Additionally, the pytest test-runner is used for running the associated test suite located in the tests/ directory.

Project versioning

This project is configured to use setuptools_scm to manage and track the project’s current release version. By using setuptools_scm, this project’s setup.py pulls the version number directly from the latest git tag associated with the project. Therefore, instead of manually setting a global __version__ variable in the application, you simply add a tag when commiting a new version of this project to the master branch.

Documentation using Sphinx and reStructuredText

Todo

  • If this project is not complex enough to require the use of full-fledged Sphinx documentation, feel free to:

    • Delete this section of README.rst

    • Delete the docs/ directory

    • Delete the docs test environment from tox.ini and .github/workflows/ci-test-matrix.yml.

This project is configured to use reStructuredText and Sphinx to generate and maintain project documentation. By defult, sphinx has been added as a dev-packages requirement to this project’s Pipfile. Therefore, when you run pipenv install --dev for the first time for your new project sphinx will be installed to your pipenv virtual environment by default.

Sources and additional resources

Todo

  • Add links to further reading and/or important resources related to this project.