Software version 0.1.0
Last updated May 31, 2025.

Welcome to the scikit-package official documentation!

scikit-package offers tools and practices for the scientific community to make better and more reusable Scientific Python packages and applications.

How does scikit-package benefit scientists?

scikit-package offers step-by-step instructions for reusing and sharing code, starting from something as simple as defining and using functions, all the way to maintaining and releasing a fully documented open-source package on PyPI and conda-forge.

Here are the 3 goals of scikit-package for the scientific community:

  1. We help scientists share scientific code to amplify research impact.

  2. We help scientists save time, allowing them to focus on writing scientific code.

  3. We offer best practices from the Billinge group’s experience in developing scientific software.

Here is an overview of the five levels of reusing and sharing code and the key features of scikit-package:

Diagram of 5 levels of sharing code with key features and scikit-package commands

The steps are divided into five levels of shareability and complexity, allowing users to choose the level that best suits their current needs. Code can be moved to higher levels as necessary.

  • Level 1, function, which is already widely used, consists of simply defining functions within the same file or module.

  • Level 2, module, expands on Level 1 by reusing functions across separate module files within the same directory.

  • Level 3, workspace, restructures the organization so that a block of code can be reused across multiple projects.

  • Level 4, system, enables users to create a lightweight package so that the code can be reused across all files locally.

  • Level 5, public, is the final step, where the source code is uploaded online so that anyone in the world can install the package, sourced from PyPI or conda-forge.

Who is using scikit-package?

The full list of packages is as follows:

How do I get started?

Please visit the Overview page to learn how to navigate the documentation!

Demo

Here is how you can use the package create public command to create a new Level 5 Python package called diffpy.my-project in just 1–2 minutes:

Demo of generating a new Level 5 package using scikit-package

Of course, you can start a lightweight package (Level 4) using the package create system command.

What are the full benefits when I reach Level 5?

  • Streamline the release process by pushing a Git tag to trigger a sequence of actions: publishing to PyPI and GitHub, updating hosted documentation, and updating the CHANGELOG.rst file.

  • Host documentation with a public URL using a Sphinx template. Include live rendering, API documentation, and previews for each pull request.

  • Provide a rich README.rst template that includes badges, installation instructions, support contacts, and contribution guidelines for your GitHub repository.

  • Set up both local and remote pre-commit hooks to automate linting of code. This includes checks for PEP8, PEP 256, and static files such as .json, .yml, and .md. Include spelling checks as well.

  • Run pytest with the latest Python versions, adhering to the SPEC0 specification, without requiring manual configuration.

  • Support namespace package imports (e.g., import <org-name>.<package-name>) to maintain branding consistency and avoid name collisions.

For technical users, here are some of the advanced features:

  • Generate conda-package meta.yaml with package create conda-forge.

  • Support headless GitHub CI testing for GUI applications.

  • Support non-pure Python package releases with cibuildwheel.

  • Reusable GitHub Actions workflows located in scikit-package/release-scripts.

How do I receive support?

If you have any questions or have trouble, please read the Frequently asked questions (FAQ) section to see if your questions have already been answered. If there aren’t answers available, please create GitHub Issues.

How can I contribute to scikit-package?

Do you have any new features? Please make an issue via the GitHub issue tracker for further discussions. For a minor typo or grammatically incorrect sentence, please make a pull request. Before making a PR, please run pre-commit run --all-files to ensure the code is formatted.

Authors

scikit-package is developed by Billinge Group and its community contributors.

For a detailed list of contributors, see https://github.com/scikit-package/scikit-package/graphs/contributors.

Acknowledgements

The Billinge Group’s scikit-package has been modified from the NSLS-II scientific cookiecutter: https://github.com/nsls-ii/scientific-python-cookiecutter