Python First Library

Tag, Release, and Publish

2020-06-07T23:04:56+00:00

Change current working directory to your project repository…

cd ~/git/hub/development-tutorials/python-first-library

Add and commit changes…

git add .

git commit -m 'Adds source files for Python library'

Tag last commit for release and push to GitHub…

git tag --annotate v0.0.1 -m ':bookmark: Initial RFC'

git push hub master

git push hub v0.0.1

Make a new release on GitHub (optional as of Python version 3 or greater)…

Example: https://github.com/development-tutorials/python-first-library/releases/new
Syntax: https://github.com/<Account>/<Repository>/releases/new

Publish to PyPi servers

python3 setup.py sdist bdist_wheel

twine upload --repository testpypi dist/python-first-library-0.0.1*
# twine upload dist/python-first-library-0.0.1*

Note, there will be new directories and files generated by the build process…

build/lib directory, contains directories and files that will be packaged into an archive

dist/ directory, contains archives that will be uploaded to PyPi servers

. python_first_library.egg-info/ directory, contains various metadata about the library

… these directories do not need to be tracked by Git, so it’s generally okay to add patterns to the .gitignore file to ignore tracking them by default.

Warning if at any point files are removed from the library (eg. via git rm path), then file(s) will also need to be removed from the build/lib directory structure.

Write Command Line Interface

2020-06-06T23:11:56+00:00

Change current working directory to your project repository…

cd ~/git/hub/development-tutorials/python-first-library

`python_first_library/cli/init.py`

[python_first_library/cli/init.py]: #python_first_librarycli__init__py “”

#!/usr/bin/env python3


from argparse import ArgumentParser
from os.path import basename
from sys import argv

from python_first_library import First_Library


__license__ = """
First Python Library example usage script
Copyright (C) 2020 S0AndS0

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, version 3 of the License.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.
"""


arg_parser = ArgumentParser(prog = basename(argv[0]),
                            usage = '%(prog)s --string "Spam!" --float 4.2',
                            epilog = 'https://github.com/S0AndS0')

arg_parser.add_argument('--string',
                        help = 'String like argument',
                        required = True,
                        type = str)

arg_parser.add_argument('--float',
                        help = 'Optional, float like argument',
                        required = False,
                        default = 1.0,
                        type = float)

arg_parser.add_argument('--license',
                        help = 'Prints license and exits',
                        required = False,
                        default = False,
                        action = 'store_true')

arg_parser.add_argument('--verbose', '-v',
                        help = 'Loudness of this script',
                        action = 'count',
                        default = 0)


args = vars(arg_parser.parse_args())

first_library = First_Library(**args)


def main():
    if args.get('license'):
        print(__license__)
        exit(0)

    first_library.print_keyword_arguments()

The main function is what is defined within the console_scripts parameter of the setup.py script, installation process will generally cross-link things correctly such that for MS devices a .exe file suffix is appended, or executable permissions are assigned for Unix devices.

Write Library

2020-06-05T23:11:56+00:00

Change current working directory to your project repository…

cd ~/git/hub/development-tutorials/python-first-library

`python_first_library/init.py`

[python_first_library/init.py]: #python_first_library__init__py “”

#!/usr/bin/env python3


if __name__ == '__main__':
    raise NotImplementedError('Please import First_Library instead')


__license__ = """
First Python Library example usage script
Copyright (C) 2020 S0AndS0

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, version 3 of the License.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.
"""


class First_Library(object):
    """docstring for First_Library."""

    def __init__(self, **keyword_arguments):
        super(First_Library, self).__init__()
        self.keyword_arguments = keyword_arguments

    def print_keyword_arguments(self):
        print(self.keyword_arguments)

When installed via pip, the class from this library will be importable via from python_first_library import First_Library

Package Setup

2020-06-04T23:11:56+00:00

Change current working directory to your project repository…

cd ~/git/hub/development-tutorials/python-first-library

# `MANIFEST.in`

The MANIFEST.in configuration file is where project files that are not automatically detected can either be included, or excluded, within build process…

include .github/README.md

… for this tutorial the ReadMe file is included, because by default setuptools will not include files within the .github directory.

# `setup.cfg`

The setup.cfg configuration file is able to define much more than metadata, and the official Python Docs – Writing the setup.cfg Configuration File is worthy of review…

[metadata]
description-file = .github/README.md

… for this tutorial the the ReadMe file is defined as the description-file to notify web-based documentation scripts where to pull data from.

# `setup.py`

The setup.py script is called by setuptools

#!/usr/bin/env python3


from setuptools import (find_packages, setup)


with open(".github/README.md", "r") as fh:
    long_description = fh.read()


setup(
    name = 'python_first_library',
    version = '0.0.1',
    author = '<account_name>',
    author_email = '<account_name>@<domain>.<tld>',
    description = 'An example Python library',
    license = 'AGPL-3.0'
    long_description = long_description,
    long_description_content_type = 'text/markdown',
    url = 'https://github.com/development-tutorials/python-first-library',
    packages = find_packages(),
    entry_points = {
        'console_scripts': [
            'watch_path = python_first_library.cli:main'
        ],
    },
    install_requires = [],
    classifiers = [
        'Development Status :: 1 - Alpha',
        'Intended Audience :: Developers',
        'Topic :: Software Development',
        'Programming Language :: Python :: 3',
        'License :: OSI Approved :: GNU Affero General Public License v3',
        'Operating System :: POSIX :: Linux',
    ],
)

# Notes about `setup.py`

name, the name of your project this value is pre-pended within project archive files under the dist/ directory
version, tag and/or release version this value is inserted within project archive files under the dist/ directory
author, your account name
author_email, a valid email address used to contact you
description, short (less than 80 characters) description of your project
license, the code/abbreviation for chosen license, the OpenSource.org chart lists most of the popular licenses with their abbreviations
url HTTP URL to source code for your project
entry_points["console_scripts"] list name of executable(s), import path, and function to call
classifiers, check the Python Packaging – Classifiers for complete listing of all valid options

Make ReadMe

2020-06-03T23:11:56+00:00

Change current working directory to your project repository…

cd ~/git/hub/development-tutorials/python-first-library

# Option One

Make a simple ReadMe file…

cd ~/git/hub/development-tutorials/python-first-library


mkdir .github
touch .github/README.md

Following is an example template that can be edited manually…

# Python First Library
[heading__top_of_document]: #python-first-library "Top of document"

------

- [Python First Library][heading__top_of_document]

- [Installation][heading__installation]

- [Usage][heading__usage]

- [Notes][heading__notes]

- [Attribution][heading__attribution]

- [License][heading__license]

------

## Installation
[heading__installation]: #installation "How to install this project"

Install to user account via...

    pip3 install --user python_first_library

## Usage
[heading__usage]: #usage "How to utilize this project"

Import within Python shell or script via...

    from python_first_library import First_Library

## Notes
[heading__notes]: #notes "Things to keep in mind when using the project"

    Anything else note worthy?

## Attribution
[heading__attribution]: #attribution "Resources that where helpful in building this project"

- [GitHub -- `development-tutorials/python-first-library`](https://github.com/development-tutorials/python-first-library)

## License
[heading__license]: #license "Legal side of Open Source software"

This project is released under the [AGPL version 3](/LICENSE) license

# Option Two

The following examples make use of GitHub – github-utilities/make-readme project which builds ReadMe files from MustacheJS templates.

Initialize ReadMe file via template…

mkdir -vp ~/git/hub/github-utilities

cd ~/git/hub/github-utilities

git clone git@github.com:github-utilities/make-readme.git

cd ~/git/hub/github-utilities/make-readme

Install NPM dependencies…

npm install

Edit github-utilities/make-readme – dataView.json

{
  "gfm": true,
  "email": "account@host.tld",
  "author": "S0AndS0",
  "organization": "development-tutorials",
  "repository": "python-first-library",
  "output_directory": "~/git/hub/development-tutorials/python-first-library",
  "description": "Example library for use within other Python projects",
  "include_notes": true,
  "include_shields_io": true,
  "license": "AGPL-3.0",
  "gh_pages": true,
  "verbose": true,
  "clobber": true,
  "quick_start": {
    "is_awk_script": false,
    "is_github_action": false,
    "is_node_package": false,
    "is_python_package": true,
    "is_submodule": false
  },
  "requirements": {
    "utilizes_awk": false,
    "utilizes_npm": false,
    "utilizes_github_actions": false,
    "utilizes_pip": false,
    "utilizes_submodules": false
  },
  "files": [
    {
      "in_path": ".mustache/.github/README.md.mst",
      "out_path": ".github/README.md",
      "partials": [
        ".mustache/partials/readme/quick_start/clone.md.mst",
        ".mustache/partials/readme/quick_start/is_awk_script.md.mst",
        ".mustache/partials/readme/quick_start/is_node_package.md.mst",
        ".mustache/partials/readme/quick_start/is_github_action.md.mst",
        ".mustache/partials/readme/quick_start/is_python_package.md.mst",
        ".mustache/partials/readme/quick_start/is_submodule.md.mst",
        ".mustache/partials/readme/requirements/utilizes_awk.md.mst",
        ".mustache/partials/readme/requirements/utilizes_github_actions.md.mst",
        ".mustache/partials/readme/requirements/utilizes_npm.md.mst",
        ".mustache/partials/readme/requirements/utilizes_pip.md.mst",
        ".mustache/partials/readme/requirements/utilizes_submodules.md.mst",
        ".mustache/partials/readme/notes.md.mst"
      ]
    }
  ]
}

Make output directory for ReadMe file and generate new ReadMe file from template…

mkdir ~/git/hub/development-tutorials/python-first-library/.github

npm run make-readme

Initialize Project

2020-06-02T23:11:56+00:00

Make directory path(s) to keep things organized…

mkdir -vp ~/git/hub/development-tutorials

Initialize new Git repository…

git init ~/git/hub/development-tutorials/python-first-library

Note, throughout this tutorial the python-first-library repository directory should be replaced with the directory name for your library.

Change current working directory to your new project repository…

cd ~/git/hub/development-tutorials/python-first-library

… add hub as a remote…

git remote add hub git@github.com:development-tutorials/python-first-library.git

Note, URL syntax is git@github.com:<account>/<repository>.git

… touch files for setuptools into existence…

touch .gitignore
touch MANIFEST.in
touch requirements.txt
touch setup.cfg
touch setup.py

… finally make directory structure for project source code, and touch files for library and Command Line Interface example into existence…

mkdir -vp python_first_library/cli


touch python_first_library/__init__.py
touch python_first_library/cli/__init__.py

# Notes about files

.gitignore defines directory and file patterns that Git should ignore from version tracking
MANIFEST.in defines files not automatically detected by setuptools that need to be included within package archive
requirements.txt should define developer dependencies, note install dependencies will need to be defined within setup.py file
setup.cfg defines metadata about this project and may be used by code linters (code style enforcement tools)
setup.py is read/executed during installation process when pip install <name> is issued by users of this project
python_first_library/__init__.py will contain the main class(s) for this project that other projects should import
python_first_library/cli/__init__.py will contain fully functional example usage of project code as a command line application

Setup Environment

2020-06-01T23:11:56+00:00

Install pip by following PyPa documentation if pip3 --version returns an error.

Install Python environment dependencies to user account…

pip3 install --user setuptools twine wheel

Documentation links for above dependencies;

Read The Docs – setuptools “Setuptools is a fully-featured, actively-maintained, and stable library designed to facilitate packaging Python projects…“
Read The Docs – twine “Twine is a utility for publishing Python packages on PyPI.”
Read The Docs – wheel “This library is the reference implementation of the Python wheel packaging standard, as defined in PEP 427.”

Register PyPi Accounts

2020-05-31T23:11:56+00:00

# Testing Repository

Utilizing the testing repository is a good idea, because deleting and/or editing mistakes within the official publishing repository is not generally allowed.

Testing Repository installation syntax adds --index-url https://test.pypi.org/simple/ and --no-deps <Package_Name>-<Account_Name> options, eg…

python3 -m pip install\
  --index-url https://test.pypi.org/simple/\
  --no-deps python-first-library-S0AndS0

Note, the --no-deps flag tells Pip to not install dependencies from the testing URL, this is important to avoid errors during installation, and testing.

# Publish Repository

Please do not skip setting up 2 Factor Authentication, because you’ll be publishing code for others to make use of.

# Example `~/.pypirc`

[pypi]
  username = __token__
  ## Test
  password = pypi-API_TEST_KEY...
  ## Publish
  # password = pypi-API_PUBLISH_KEY...

Python First Library

Tag, Release, and Publish

Write Command Line Interface

python_first_library/cli/__init__.py

Write Library

python_first_library/__init__.py

Package Setup

# MANIFEST.in

# setup.cfg

# setup.py

# Notes about setup.py

Make ReadMe

# Option One

# Option Two

Initialize Project

# Notes about files

Setup Environment

Register PyPi Accounts

# Testing Repository

# Publish Repository

# Example ~/.pypirc

`python_first_library/cli/init.py`

`python_first_library/init.py`

# `MANIFEST.in`

# `setup.cfg`

# `setup.py`

# Notes about `setup.py`

# Example `~/.pypirc`