From Code to Open‑Source: A Step‑by‑Step Guide to Publish Your Python Package

Publishing a Python project as an open‑source package involves several systematic steps. This guide uses the SciTime project as an example to illustrate the entire workflow.

Step 0: Add a License

Choose a suitable open‑source license (e.g., MIT or BSD) and place a LICENSE file in the repository root.

Step 1: Prepare Your Code

Ensure the project layout is correct: a top‑level folder named after the package contains the core modules, each with an __init__.py. Use the logging module instead of print statements and organize functionality into classes.

from .estimate import Estimator

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

Place a setup.py file in the repository root to automate packaging and distribution. Example:

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: Set Up Local Tests and Coverage

Write unit tests (e.g., with pytest) in a dedicated tests/ folder and run them via python -m pytest. Use tools like codecov and a .coveragerc file to measure coverage.

comment: false

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

Step 4: Enforce Code Style

Ensure the code follows PEP 8 using tools such as flake8.

Step 5: Write Documentation

Create a comprehensive README.md and, if needed, generate detailed docs with sphinx hosted on Read the Docs. Include pull‑request and issue templates, as well as a contribution guide.

Step 6: Set Up Continuous Integration

Configure CI services (e.g., Travis CI, AppVeyor) to run tests, check style, and upload coverage after each commit. Example .travis.yml snippet:

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

Step 7: Create a Release and Publish

Tag a new release on GitHub, then publish the package. For PyPI, use twine (e.g., python setup.py sdist followed by twine upload dist/*). For Conda, submit the recipe to conda‑forge.

After publishing, maintain the project by updating the version, creating new releases, and repeating the release steps as needed.