From Code to Open‑Source: A Step‑by‑Step Guide to Publishing a Python Package

Step 0: Get a License

Before anything else, add an open‑source license (e.g., MIT or BSD) to the repository root as LICENSE. Follow GitHub’s guide for adding a license.

Step 1: Prepare Your Code

Ensure a clean project layout: a top‑level folder named after the project containing core modules and an __init__.py that exposes the public API and version. Use the logging module for proper logging and organize functionality into classes. from .estimate import Estimator Example of a logging mixin used by other classes:

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)
        return logging.getLogger(name)

Step 2: Create setup.py

Add a setup.py file at the repository root to automate packaging and distribution. Below is a minimal 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'
)

Key Points for setup()

List dependencies via install_requires or a requirements.txt file.

Include data files with package_data.

Refer to the official setuptools documentation for more options.

Step 3: Set Up Local Tests and Coverage

Write unit tests (e.g., with pytest) in a dedicated tests/ folder. Run them locally using python -m pytest. Use codecov and a .coveragerc file to enforce coverage thresholds.

comment: false

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

[run]
branch = True
source = scitime
include = */scitime/*
omit =
    */_data.py
    */setup.py

Step 4: Enforce Code Style

Make sure the code follows PEP 8; tools like flake8 can automate style checks.

Step 5: Write Good Documentation

Create a comprehensive README.md and consider using Sphinx for full documentation hosted on Read the Docs. Add pull‑request and issue templates, a contribution guide, a code of conduct, and useful badges.

Step 6: Set Up Continuous Integration

Configure CI (e.g., Travis CI, AppVeyor) to run tests, check coverage, and enforce style on every push. Example .travis.yml:

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

Step 7: Release the Package

Tag a new release on GitHub, then publish to PyPI with twine or to Conda‑Forge. For PyPI, build the source distribution ( python setup.py sdist) and upload ( twine upload dist/*). For Conda, submit a recipe to conda‑forge.

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 release, maintain the project by updating the version, creating new releases, and repeating the steps as needed.