From a Python Project to an Open‑Source Package: Step‑by‑Step Guide

This article provides a detailed, step‑by‑step guide for publishing a Python project as an open‑source package on GitHub.

Step 0 – Choose a License : Add a LICENSE file (e.g., MIT or BSD) to the repository root using GitHub’s license‑adding guide.

Step 1 – Prepare Your Code : Ensure a proper project layout with a top‑level package folder containing modules and an __init__.py that exposes the public API. Use the logging module for logging and organize core functionality into classes.

Example import statement: from .estimate import Estimator Example logging mixin:

import logging

class LogMixin(object):
    @property
    def logger(self):
        name = '.'.join([self.__module__, self.__class__.__name__])
        FORMAT = '%(name)s:%(levelname)s:%(message)s'
        logging.basicConfig(format=FORMAT, level=logging.DEBUG)
        logger = logging.getLogger(name)
        return logger

Step 2 – Create setup.py : Add a setup.py at the repository root to automate packaging and distribution. The guide includes a full example that reads README.md, specifies dependencies, metadata, and package data.

Example setup.py snippet:

from setuptools import setup
from os import path

DIR = path.dirname(path.abspath(__file__))
INSTALL_PACKAGES = open(path.join(DIR, 'requirements.txt')).read().splitlines()

with open(path.join(DIR, 'README.md')) as f:
    README = f.read()

setup(
    name='scitime',
    packages=['scitime'],
    description='Training time estimator for scikit-learn algorithms',
    long_description=README,
    long_description_content_type='text/markdown',
    install_requires=INSTALL_PACKAGES,
    version='0.0.2',
    url='http://github.com/nathan-toubiana/scitime',
    author='Gabriel Lerner & Nathan Toubiana',
    author_email='[email protected]',
    keywords=['machine-learning', 'scikit-learn', 'training-time'],
    tests_require=['pytest', 'pytest-cov', 'pytest-sugar'],
    package_data={'': ['*.json', 'models/*.pkl', 'models/*.json']},
    include_package_data=True,
    python_requires='>=3'
)

Step 3 – Local Testing & Coverage : Write unit tests (e.g., with pytest) in a dedicated tests/ folder and run them via python -m pytest. Use coverage tools like codecov and configure .codecov.yml and .coveragerc to enforce thresholds.

Example .codecov.yml snippet:

comment: false
coverage:
  status:
    project:
      default:
        target: auto
        threshold: 10%
    patch:
      default:
        target: auto
        threshold: 10%

Step 4 – Code Style : Ensure PEP‑8 compliance using tools such as flake8.

Step 5 – Documentation : Create a comprehensive README.md and, if needed, generate full documentation with Sphinx hosted on Read the Docs. Include contribution guides, issue and pull‑request templates.

Step 6 – Continuous Integration : Automate testing, style checks, and coverage on each push using CI services. The guide shows configurations for Travis CI, AppVeyor, and webhook integration with Codecov and Read the Docs.

Example .travis.yml snippet:

language: python
python:
  - "3.6"
install:
  - pip install -r requirements.txt
  - pip install flake8
  - pip install pytest-cov
  - pip install codecov
script:
  - python -m pytest --cov=scitime
  - ./build_tools/flake_diff.sh
after_success:
  - codecov

Example appveyor.yml snippet:

environment:
  matrix:
    - PYTHON: "C:\\Python36-x64"
install:
  - "%PYTHON%\\python.exe -m pip install -r requirements.txt"
  - "%PYTHON%\\python.exe -m pip install pytest==3.2.1"
build: off
test_script:
  - "%PYTHON%\\python.exe -m pytest"

Step 7 – Release & Publication : Create a GitHub release to tag a version, then publish the package. For PyPI, use twine after building a source distribution ( python setup.py sdist). For Conda, submit the recipe to conda‑forge.

Final repository layout example (shown as a tree):

your_package/
  __init__.py
  your_module.py
docs/
tests/
setup.py
.travis.yml
appveyor.yml
.coveragerc
.codecov.yml
README.md
LICENSE
.github/
  CODE_OF_CONDUCT.md
  CONTRIBUTING.md
  PULL_REQUEST_TEMPLATE.md
  ISSUE_TEMPLATE/

After publishing, maintain the project by updating versions, creating new releases, and repeating the final step for each significant change.