Package: template-python-library
|Documentation|Introduction{update_here}This package is an example/template for building repositories. The choices made
in this repository are based on a combination of experience, convenience, and current
convention. These factors will change over time, and as such so will/should the
recommendations made in this document.This package works like a normal package, it can be installed, tests can be run,
it can be linted, coverage will be calculated, it should even push to pypi on push
to master (merge accepted).In the following, we briefly provide information about the format of this repository,
this is followed by the boilerplateREADME.mdsections that describe how to install,
how to run examples, how to run tests, how to get coverage, how to lint, etc.Throughout this file, and the other files in this template, replace{my_pacakge}with the name of the new repository that you are creating. Also, replace{template_python_library},{REPLACE}, and{update_here}as appropriate.Things already setup in this repository:github action (GHA) for running tests:https://github.com/gattia/template_python_library/blob/main/.github/workflows/build-test.ymlGHA for running tests, building, and deploying to pypi:https://github.com/gattia/template_python_library/blob/main/.github/workflows/building-pypi-linux.ymlStructure is there for building wheels, but commented out because this package
only has native python code.cibuildwheel is setup / used for deploying wheels to pypi, and includes building
for multiple difference OSes.GHA for building docs:https://github.com/gattia/template_python_library/blob/main/.github/workflows/building-pypi-linux.ymlUsespdoc3could build a branch of this repository for building sphinx / readthedocs? But why not use GitHub Pages? even if sphinx?General structure/code (make file), dependicies for creating docs automatically from docstrings.Use numpy docstrings to enable this:https://numpydoc.readthedocs.io/en/latest/format.htmlThe example code already has numpy formatting to start.pyproject.toml to describe metadata & build infoThis uses latest PEP621 recommendations for packaging - supersedessetup.pyandsetup.cfglinting usingisortandblack. Settings inpyproject.tomlTemplate information/outline for contributing (borrowed from DOSMA)License (MIT by default - change as appropriate).gitignore for the current repo / common python uses.testing structure, example, dependency (pytest), and commands to run (make test).code structure, example, including docstringsmake file to easily run commands like building, installing, linting, etc.To do:[] give coverage badge onREADME.mdStructureHere is the general structure of this setup. Below this structure are quick instructions of
things to change for your new repository.Instructions onPackagingfrom python are provided here:https://packaging.python.org/en/latest/tutorials/packaging-projects/template_python_library/                      
    template_python_library/ 
        __init__.py
        files.py
        modules/
            __init__.py
            more_files.py
    
    .github/
        ISSUE_TEMPLATE/
            bug_report.md # template for filing bugs
            feature_request.md # template for feature requests
        workflows/
            build-test.yml 
                # github actions workflow to:
                #   - test linting/formating
                #   - build & test the package
                # To work, this requires a number of the Make commands to 
                # be setup, including: dev, requirements, lint, test
    
    docs/
        # folder where the docs will be built
    
    examples/ 
        # folder where example scripts should be placed. 
        # e.g., https://github.com/gattia/cycpd/tree/main/examples
    
    .gitignore
        # pre-filled gitignore file for common python packages & specific to this repo. 
    
    Makefile
        # makefile with convenienience commands designed to make 
        # developing/installing easier. 
    
    pyproject.toml
        # file to specify metadata of the project, requirements, etc. 
        # this replaces `setup(...)` in a normal `setup.py` file. 
        # also includes description of configurations for other build tools
        # such as linting, (isort, black). 
        # information for setting up `pyproject.toml`: https://peps.python.org/pep-0621/
        # other helpful resources: 
        #    https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html
        #    https://scikit-hep.org/developer/pep621


    README.md 
        # current background info, install info, and how to contribute

    setup.py 
        # file to call to build library `python setup.py install`
        # setup.py is no longer encouraged. We provide the most basic one here
        # because it is still needed to install in editable mode.This is only 
        # needed for editable mode because `pyproject.toml` does not fully support 
        # editable mode, yet:
        #   https://setuptools.pypa.io/en/latest/userguide/quickstart.html#development-mode
        #
        # also, the setup.py might be needed for installing cython dependencies
        # Example here: https://github.com/gattia/cycpd/blob/e235da5276652eea12875aef3c8280a9b673122e/setup.py#L12-L20
        # and here: https://github.com/gattia/cycpd/blob/e235da5276652eea12875aef3c8280a9b673122e/setup.py#L48
    
    requirements.txt
        # packages that this repository requires/ that should be installed first 
        # this is necessary to let conda install dependencies (as well as pip). 
        # These requirements could be placed inside of the pyproject.toml
        #     - But can conda read the pyproject.toml?

    CONTRIBUTING.md 
        # information about how to contribte to the library
        # this format overall was bored from DOSMA
    
    LICENSE
        # Package license / license type.Steps to update this package for new repository:findall instances of{my_project},{REPLACE},template_python_library, and{update_here}and
replace with package name or other information as appropriate.(1) should include renaming this current directory, and the source directory (template_python_library)fill in the"description"in thepyproject.tomlupdaterequirements.txtanddependenciesinpyproject.tomlTo do - can dependencies read/update from requirements.txt?ADD INSTRUCTIONS TO STOP TRACKING THIS GITHUB REPOSITORY.Initiate new github repoStart committing to itPush to new github repository.After pushing to new repository on github, make sure to allow github pages so properly so that the docs
will automatically build. Go to theSettingstab on your github repo, underPageson the left,
turn GitHub Pages on, and select the home dir for the docs to be/docson themainbranch. There is a
screen shot at the end of this README pointing to the relevant fields.If there is a problem finding the package structure when building (finds tests and can't disambiguate),
then you can specify package information inpyproject.toml[tool.setuptools]. This is flagged with{REPLACE}. See here for more info:https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html#dynamic-metadataThis describes a system similar to definingpackages=['pymskt', 'pymskt.image', etc.]insetup()InstallationYou should be able to install this by cloning, navigating to this root directory, and installing with pip:git clone https://github.com/gattia/template_python_library
cd template_python_library

conda create -n template_python_library python=3.8

pip install . 

# OR
make installInstall for developmentThis method of install will install in editable mode. This means that the code wont be packaged and saved
in your python'ssite-packages, insteadsite-packageswill point to this directory. So, if the code
changes in here, so will the version of this package used on your local build.git clone https://github.com/gattia/template_python_library
cd template_python_library

conda create -n template_python_library python=3.8

make dev
make install-devExamplesDescribe how to use the examples. E.g., {update_here}Navigate to the examples directory and run the scripts:cdexamples
pythonexamples/example_1.pyDevelopment / ContributingTestsThe test can be run by:pytestormaketestInidividual tests can be run by runningpython -m pytests path_to_testCoverageCoverage results/info requirescoverage(conda install coverageorpip install coverage).These should be installed automatically with one of themake devcommands.You can get coverage statistics by running:coverage run -m pytestor if using make:make coverageThis will save an html of the coverage results.note about coverage:- Coverage runs by seeing how much of the code-base is covered when you run the command after coverage. 
In this case, it is looking to see how much of the code-base is covered when we run the tests.ContributingIf you want to contribute, please read over the documentaiton inCONTRIBUTING.mdDocsTo build the docs, runmake docs. If you want the docs published on gihutb, you need to activate github page.
Go to theSettingstab on your github repo, underPageson the left, turn GitHub Pages on, and select the
home dir for the docs to be/docson themainbranch. Example here:LicenseMIT License