Package: fair-python-cookiecutter
fair-python-cookiecutterAn opinionated cookiecutter template to kickstart a modern best-practice Python project with FAIR metadata.Check out thedemo repositorygenerated from this template!OverviewAre you aresearcherorresearch software engineer?Did you somehow end up developingPython tools and librariesas part of your job?Are you overwhelmed and confused by the increasing demands to research software?Regardless whether you are just planning to start a new software project, or you just
look for ideas about how you could improve its quality -this template is for you!Unlike myriads of other templates, this template targets the typical case in academia -
you built some nice little tool or library for your scientific community,
and hope that others have agood experience- you want to provide aquality
productthat others enjoy using. In case they actually do use it with some success, you
might also like to be acknowledged - for example, by having your toolcited.To ensure quality, there are manybest practicesand recommendations forsoftware
developmenton various levels, both general as well as Python-specific. To help others
find your project and also enable them to cite it, there are also recommendations
concerning your software projectmetadata. In fact, there are so many recommendations
that it can be hard to keep up and easy to become overwhelmed and confused.To save you some time navigating all of that advice and figuring out how to apply it in
practice, we did the work for you and provide you with this template!
You can use it as is, adapt it, or at least get some inspiration for your projects.Main FeaturesThis template sets up a skeleton for a Python project that:uses modern state-of-the-art development toolsprovides a baseline for professional development and maintenancehelps following best practices for code and metadata qualitycontains detailed documentation on how to work with itIt is built to help you adopting good practices
and follow recommendations such as:DLR Software Engineering GuidelinesOpenSSF Best PracticesNetherlands eScience Centerinnumerable other resources that can be found onlineFurthermore, it implements emerging standards with the goal to improve
software metadata and make it moreFAIR:REUSECITATION.cffCodeMetaAlso seethis paperfor an overview and
recommendations on the state of software citation in academic practice.Getting StartedMake sure that you have a working Python interpreter in version at least 3.8,gitandpoetryinstalled.To install the template, runpip install fair-python-cookiecutter.Now you can use the tool to generate a new Python project:fair-python-cookiecutterYourProjectNameThis will spawn an interactive prompt, where you have to provide some information and
make some choices for your new software project. Don't worry, you can always adapt
everything later on by hand. After this, your software project will be created in
a new directory.To save you some time answering the questions, we recommend that you create an empty repository
in GitHub or GitLab of your choice (i.e., the location where you plan to push your new project).If you already have created an empty remote repository or know exactly its future
location, you can provide the URL, which already will provide many required inputs:fair-python-cookiecutter--repo-urlhttps://github.com/YourOrganization/YourProjectNameYour new project repository will also include a copy of adeveloper guide,
containing more information about the structure and features of the generated project.Please familiarize yourself with the generated structures, files and the contents of the
developer guide.Feel free to either remove the guide afterwards, or keep (and possibly
adjust) it as extended technical project documentation for yourself and other future
project contributors.You can find a demo repository generated from this templatehere.Configuring the TemplateIf you intend to use the template a lot, e.g. if you want to use (an adaptation of)
this template as the default way to start a Python project for yourself and/or others,
you might want to configure some template variables in your~/.cookiecutterrc.
Here is an example cookiecutter configuration:fair_python_cookiecutter:last_name:"Carberry"first_name:"Josiah"project_keywords:"psychoceramicsanalytics"email:"josiah.carberry@brown.edu"orcid:"0000-0002-1825-0097"affiliation:"BrownUniversity"copyright_holder:"BrownUniversity"license:"MIT"This information will be already pre-filled when you use the template,
saving you some time and possibly avoiding possible mistakes from manual typing.Modifying the TemplateIf you want to adjust it to your needs and likings (e.g. add, remove or substitute certain
tools), you probably want toforkit to get your own copy. Then you can do the desired changes and use the URL of your
template repository instead of this one to kickstart your projects.However, if you think that your changes are of general interest and would improve this
template for a majority of users, please get in touch
andcontributeorsuggestan improvement!In any case we are very happy to know about any similar or derivative templates, e.g. for
more specific use-cases or based on other tool preferences.Reusing Parts of the TemplateIf you already have an existing project where you would like to introduce things you like
from this template, there are two main ways to do so:move your code into a fresh repository based on this templateuse parts of the template in your existing project structureIf your project currently has no sophisticated setup of tools or strong preferences about
them, option 1 might be the simplest way to adopt the template. Your code then needs to be
moved into theYOUR_PROJECT/src/YOUR_PACKAGEsubdirectory.On the other hand, if you already have a working setup that you do not wish to replace
completely, you can take a look atthe.pre-commit-config.yamlfile to adopt some of the quality assurance tools listed therethe CI pipelines defined in.github/workflowsor.gitlab-ci.ymlfor automated tests and releasesthemkdocs.ymlanddocs/subdirectory to see how the project website worksHow to CiteIf you want to cite this project in your scientific work,
please use thecitation filein therepository.AcknowledgementsWe kindly thank allauthors and contributors.This project was developed at the Institute for Materials Data Science and Informatics
(IAS-9) of the Jülich Research Center and funded by the Helmholtz Metadata Collaboration
(HMC), an incubator-platform of the Helmholtz Association within the framework of the
Information and Data Science strategic initiative.