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
Contents
.. 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.
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.
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:
pipenvpipenv, version 2020.8.13was used for developing this script, however older versions ofpipenvwill likely work.- If you prefer NOT to use
pipenvfor packaging and virtual environment management in favor of an alternative such ascondaorvirtualenv, you will need to modify the project repository and.toxtest matrix accordingly.
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
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.
If you'd like clone and build off of this project, below are some important notes regarding the configuration of this project.
In this section
.. 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.
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.
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.
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.
- If you are new to
pytest, please see the official pytest documentation. - If you are new to
tox, please see the official Tox documentation. - If you are new to GitHub Actions, additional information can be found here.
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.
- If you are new to
setuptools_scm, please see the official documentation.
.. 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.
- For an overview of usage, or for more info on the benefits of Sphinx and reStructuredText, please see this section of this brief overview of using Sphinx to document a project
- If you are new to Sphinx, please see the Sphinx documentation
- If you are new to reStructuredText, a good starting place will be the reStructuredText documentation provided by the Sphinx project
Questions or issues related to this project can be submitted as an "issue" via the GitHub repository at: https://github.com/sedelmeyer/cc-pyscript-sample-repo/issues
.. todo::
* Add details on the best method for others to reach you regarding questions they might have or issues they identify related to this project.
.. todo::
* Add links to further reading and/or important resources related to this project.