From 85ae46a118cabbc02bdf8db6b3baa6eb80996c01 Mon Sep 17 00:00:00 2001 From: KristinaGomoryova Date: Mon, 15 Jul 2024 09:13:38 +0200 Subject: [PATCH 01/23] changelog updated --- CHANGELOG.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ebc9836..f9dd345 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,10 +6,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] -## [0.0.1] - 1900-12-31 +## [0.1.0] - 2024-07-15 ### Added +- function to read the metadata or alkane file in csv/tsv/xls/xlsx format +- function to process the metadata file: validate file names, derive and rearrange additional metadata columns +- function to save the processed metadata or alkane dataframe as tsv + ### Removed ### Changed From a26a03a5bfa49a28e181bd6c51184152fc8632d6 Mon Sep 17 00:00:00 2001 From: KristinaGomoryova Date: Mon, 15 Jul 2024 10:00:47 +0200 Subject: [PATCH 02/23] readme updated --- README.md | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index a60470a..ff29a71 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,5 @@ ## Badges -(Customize these badges with your own links, and check https://shields.io/ or https://badgen.net/ to see which other badges are available.) - | fair-software.eu recommendations | | | :-- | :-- | | (1/5) code repository | [![github repo badge](https://img.shields.io/badge/github-repo-000.svg?logo=github&labelColor=gray&color=blue)](https://github.com/RECETOX/rcx-tk) | @@ -21,9 +19,16 @@ ## How to use rcx_tk -Tools for internal use +`rcx-tk` package provides tools to process the metadata or alkane files. + +On the input, the user is expected to supply a path to the metadata/alkane file in tsv/csv/xls/xlsx file. The file is then converted to a dataframe which is further processed. The main steps are: -The project setup is documented in [project_setup.md](project_setup.md). Feel free to remove this document (and/or the link to this document) if you don't need it. +- columns rearrangement +- validation of the file names +- validation that the `injectionNumber` column is of integer type +- derivation of new metadata: `sampleName`, `sequenceIdentifier`, `sampleIdentifier` and `localOrder` + +Finally, the processed dataframe is saved into user-defined location. ## Installation @@ -35,9 +40,16 @@ cd rcx-tk python -m pip install . ``` +Upon installation, the tool can be run also using the poetry: + +```console +poetry run rcx_tk --method='' +``` + + ## Documentation -Include a link to your project's full documentation here. +The project is documented [here](https://rcx-tk.readthedocs.io/en/latest/?badge=latest). ## Contributing From ab1d64e4be0cf3f31bed3bf72fd272aa815401cf Mon Sep 17 00:00:00 2001 From: KristinaGomoryova Date: Mon, 15 Jul 2024 10:05:08 +0200 Subject: [PATCH 03/23] readme dev updated --- README.dev.md | 166 +------------------------------------------------- 1 file changed, 2 insertions(+), 164 deletions(-) diff --git a/README.dev.md b/README.dev.md index af6f34a..9969d4f 100644 --- a/README.dev.md +++ b/README.dev.md @@ -25,170 +25,8 @@ Afterwards check that the install directory is present in the `PATH` environment ## Running the tests -There are two ways to run tests. - -The first way requires an activated virtual environment with the development tools installed: - -```shell -pytest -v -``` - -The second is to use `tox`, which can be installed separately (e.g. with `pip install tox`), i.e. not necessarily inside the virtual environment you use for installing `rcx_tk`, but then builds the necessary virtual environments itself by simply running: - -```shell -tox -``` - -Testing with `tox` allows for keeping the testing environment separate from your development environment. -The development environment will typically accumulate (old) packages during development that interfere with testing; this problem is avoided by testing with `tox`. - -### Test coverage - -In addition to just running the tests to see if they pass, they can be used for coverage statistics, i.e. to determine how much of the package's code is actually executed during tests. -In an activated virtual environment with the development tools installed, inside the package directory, run: - -```shell -coverage run -``` - -This runs tests and stores the result in a `.coverage` file. -To see the results on the command line, run - -```shell -coverage report -``` - -`coverage` can also generate output in HTML and other formats; see `coverage help` for more information. - -## Running linters locally - -For linting and sorting imports we will use [ruff](https://beta.ruff.rs/docs/). Running the linters requires an -activated virtual environment with the development tools installed. - -```shell -# linter -ruff . - -# linter with automatic fixing -ruff . --fix -``` - -To fix readability of your code style you can use [yapf](https://github.com/google/yapf). - -You can enable automatic linting with `ruff` on commit by enabling the git hook from `.githooks/pre-commit`, like so: - -```shell -git config --local core.hooksPath .githooks -``` - -## Generating the API docs - -```shell -cd docs -make html -``` - -The documentation will be in `docs/_build/html` - -If you do not have `make` use - -```shell -sphinx-build -b html docs docs/_build/html -``` - -To find undocumented Python objects run +Tests were written using the pytest package and can be run as: ```shell -cd docs -make coverage -cat _build/coverage/python.txt +pytest . ``` - -To [test snippets](https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html) in documentation run - -```shell -cd docs -make doctest -``` - -## Versioning - -Bumping the version across all files is done with [bump-my-version](https://github.com/callowayproject/bump-my-version), e.g. - -```shell -bump-my-version bump major # bumps from e.g. 0.3.2 to 1.0.0 -bump-my-version bump minor # bumps from e.g. 0.3.2 to 0.4.0 -bump-my-version bump patch # bumps from e.g. 0.3.2 to 0.3.3 -``` - -## Making a release - -This section describes how to make a release in 3 parts: - -1. preparation -1. making a release on PyPI -1. making a release on GitHub - -### (1/3) Preparation - -1. Update the (don't forget to update links at bottom of page) -2. Verify that the information in [`CITATION.cff`](CITATION.cff) is correct. -3. Make sure the [version has been updated](#versioning). -4. Run the unit tests with `pytest -v` - -### (2/3) PyPI - -In a new terminal: - -```shell -# OPTIONAL: prepare a new directory with fresh git clone to ensure the release -# has the state of origin/main branch -cd $(mktemp -d rcx_tk.XXXXXX) -git clone git@github.com:RECETOX/rcx-tk . - -# make sure to have a recent version of pip and the publishing dependencies -python -m pip install --upgrade pip -python -m pip install .[publishing] - -# create the source distribution and the wheel -python -m build - -# upload to test pypi instance (requires credentials) -python -m twine upload --repository testpypi dist/* -``` - -Visit -[https://test.pypi.org/project/rcx_tk](https://test.pypi.org/project/rcx_tk) -and verify that your package was uploaded successfully. Keep the terminal open, we'll need it later. - -In a new terminal, without an activated virtual environment or an env directory: - -```shell -cd $(mktemp -d rcx_tk-test.XXXXXX) - -# prepare a clean virtual environment and activate it -python -m venv env -source env/bin/activate - -# make sure to have a recent version of pip and setuptools -python -m pip install --upgrade pip - -# install from test pypi instance: -python -m pip -v install --no-cache-dir \ ---index-url https://test.pypi.org/simple/ \ ---extra-index-url https://pypi.org/simple rcx_tk -``` - -Check that the package works as it should when installed from pypitest. - -Then upload to pypi.org with: - -```shell -# Back to the first terminal, -# FINAL STEP: upload to PyPI (requires credentials) -python -m twine upload dist/* -``` - -### (3/3) GitHub - -Don't forget to also make a [release on GitHub](https://github.com/RECETOX/rcx-tk/releases/new). If your repository uses the GitHub-Zenodo integration this will also trigger Zenodo into making a snapshot of your repository and sticking a DOI on it. From 5fd0cd7b5a67f133cda10c3da640d802b33db7f5 Mon Sep 17 00:00:00 2001 From: KristinaGomoryova Date: Mon, 15 Jul 2024 10:20:49 +0200 Subject: [PATCH 04/23] citation updated --- CITATION.cff | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CITATION.cff b/CITATION.cff index ba205a6..9b562a0 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -6,12 +6,14 @@ authors: - family-names: Ahmad given-names: Zargham - orcid: "https://orcid.org/0000-0000-0000-0000" + orcid: "" date-released: 2024-06-19 version: "0.1.0" repository-code: "https://github.com/RECETOX/rcx-tk" keywords: - rcx - process metadata + - alkanes + - metabolomics message: "If you use this software, please cite it using these metadata." license: MIT From a19410aab3aa6e7061f98d5a77b5f23d0bc9f794 Mon Sep 17 00:00:00 2001 From: KristinaGomoryova Date: Mon, 15 Jul 2024 10:21:03 +0200 Subject: [PATCH 05/23] next steps and notice files deleted --- NOTICE | 2 -- next_steps.md | 47 ----------------------------------------------- 2 files changed, 49 deletions(-) delete mode 100644 NOTICE delete mode 100644 next_steps.md diff --git a/NOTICE b/NOTICE deleted file mode 100644 index 965c3ce..0000000 --- a/NOTICE +++ /dev/null @@ -1,2 +0,0 @@ -This product includes rcx_tk, software developed by -Netherlands eScience Center. diff --git a/next_steps.md b/next_steps.md deleted file mode 100644 index affbc71..0000000 --- a/next_steps.md +++ /dev/null @@ -1,47 +0,0 @@ -# Next steps - -## Put the generated files under version control - -Once your Python package is created, put it under [version -control](https://guide.esciencecenter.nl/#/best_practices/version_control) using -[git](https://git-scm.com/) and [GitHub](https://github.com/). - -Note that the next step assumes you have setup your connection to GitHub via SSH, -see [Connecting to GitHub with SSH](https://docs.github.com/en/github-ae@latest/authentication/connecting-to-github-with-ssh). - -Alternatively, you can also use a personal access token, see -[Creating a personal access token](https://docs.github.com/en/github-ae@latest/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). If you choose this option, below you will have to replace -`git@github.com:` by `https://github.com/`. - -```shell -cd rcx-tk -git init -git add --all -git commit -m "first commit" -git branch -M main -git remote add origin git@github.com:RECETOX/rcx-tk -``` - -## Push the initial commit to a new repo on GitHub - -Go to -[https://github.com/organizations/RECETOX/repositories/new](https://github.com/organizations/RECETOX/repositories/new) -and create a new repository named `rcx-tk` as an empty repository, then push your commits to GitHub: - -```shell -git push --set-upstream origin main -``` - -## Check automatically generated issues - -A short while after you push your commits to GitHub for the first time, a few issues outlining next steps will added -automatically ([here](https://github.com/RECETOX/rcx-tk/issues?q=author%3Aapp%2Fgithub-actions)). Resolve them to complete the -setup of your repository. - -## Project development documentation - -The [README.dev.md](README.dev.md) contains developer documentation. - -## Project layout explained - -For an explanation of what files are there, and what each of these do, please refer to [project_setup.md](project_setup.md). From 57d7076fd29700b011cdeb8bf8ede842f6d6d6ed Mon Sep 17 00:00:00 2001 From: KristinaGomoryova Date: Mon, 15 Jul 2024 10:22:34 +0200 Subject: [PATCH 06/23] authors updated --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 8d81a19..20272be 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -2,7 +2,7 @@ name = "rcx-tk" version = "0.1.0" description = "This package adjusts and cleans the metadata file provided by a user." -authors = ["Zargham Ahmad " ] +authors = ["Zargham Ahmad " , "Kristina Gomoryova "] license = "MIT" readme = "README.md" keywords = ["metadata", "alkanes", "metabolomics"] From b3290752d2edd5b4dbdcd167c334544e6edb2fcd Mon Sep 17 00:00:00 2001 From: KristinaGomoryova Date: Mon, 15 Jul 2024 10:47:31 +0200 Subject: [PATCH 07/23] project_setup updated --- project_setup.md | 95 +++++++++--------------------------------------- 1 file changed, 17 insertions(+), 78 deletions(-) diff --git a/project_setup.md b/project_setup.md index 496eea5..4bc61bb 100644 --- a/project_setup.md +++ b/project_setup.md @@ -1,70 +1,44 @@ # Project Setup -Here we provide some details about the project setup. Most of the choices are explained in the -[guide](https://guide.esciencecenter.nl). Links to the relevant sections are included below. Feel free to remove this -text when the development of the software package takes off. - -For a quick reference on software development, we refer to [the software guide -checklist](https://guide.esciencecenter.nl/#/best_practices/checklist). - ## Python versions This repository is set up with Python versions: -- 3.8 -- 3.9 -- 3.10 - 3.11 - 3.12 -Add or remove Python versions based on project requirements. See [the -guide](https://guide.esciencecenter.nl/#/best_practices/language_guides/python) for more information about Python -versions. - ## Package management and dependencies -You can use either pip or conda for installing dependencies and package management. This repository does not force you -to use one or the other, as project requirements differ. For advice on what to use, please check [the relevant section -of the -guide](https://guide.esciencecenter.nl/#/best_practices/language_guides/python?id=dependencies-and-package-management). +For installing the dependencies and package management, [micromamba](https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html) and [poetry](https://python-poetry.org/) have been used. -- Runtime dependencies should be added to `pyproject.toml` in the `dependencies` list under `[project]`. -- Development dependencies should be added to `pyproject.toml` in one of the lists under `[project.optional-dependencies]`. +The dependencies are listed in the `pyproject.toml` file under the section `[tool.poetry.dependencies]` and `[tool.poetry.group.dev.dependencies]`. ## Packaging/One command install -You can distribute your code using PyPI. -[The guide](https://guide.esciencecenter.nl/#/best_practices/language_guides/python?id=building-and-packaging-code) can -help you decide which tool to use for packaging. +To create a new environment, use the micromamba: + +```console +micromamba create rcx-tk +micromamba activate rcx-tk +``` +To install all dependencies specified in the `pyproject.toml` file, use poetry: + +```console +poetry install +``` ## Testing and code coverage -- Tests should be put in the `tests` folder. -- The `tests` folder contains: - - Example tests that you should replace with your own meaningful tests (file: `test_my_module.py`) +- Tests are in the `tests` folder, in the `test_process_metadata_file.py` file. - The testing framework used is [PyTest](https://pytest.org) - - [PyTest introduction](https://pythontest.com/pytest-book/) - - PyTest is listed as a development dependency - - This is configured in `pyproject.toml` - The project uses [GitHub action workflows](https://docs.github.com/en/actions) to automatically run tests on GitHub infrastructure against multiple Python versions - - Workflows can be found in [`.github/workflows`](.github/workflows/) -- [Relevant section in the guide](https://guide.esciencecenter.nl/#/best_practices/language_guides/python?id=testing) ## Documentation -- Documentation should be put in the [`docs/`](docs/) directory. The contents have been generated using `sphinx-quickstart` (Sphinx version 1.6.5). -- We recommend writing the documentation using Restructured Text (reST) and Google style docstrings. - - [Restructured Text (reST) and Sphinx CheatSheet](https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html) - - [Google style docstring examples](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html). +- Documentation is in the [`docs/`](docs/) directory. The contents have been generated using `sphinx-quickstart` (Sphinx version 1.6.5). - The documentation is set up with the ReadTheDocs Sphinx theme. - - Check out its [configuration options](https://sphinx-rtd-theme.readthedocs.io/en/latest/). - [AutoAPI](https://sphinx-autoapi.readthedocs.io/) is used to generate documentation for the package Python objects. - `.readthedocs.yaml` is the ReadTheDocs configuration file. When ReadTheDocs is building the documentation this package and its development dependencies are installed so the API reference can be rendered. -- [Relevant section in the guide](https://guide.esciencecenter.nl/#/best_practices/language_guides/python?id=writingdocumentation) - -## Coding style conventions and code quality - -- [Relevant section in the NLeSC guide](https://guide.esciencecenter.nl/#/best_practices/language_guides/python?id=coding-style-conventions) and [README.dev.md](README.dev.md). ## Continuous code quality @@ -75,43 +49,8 @@ help you decide which tool to use for packaging. ## Package version number -- We recommend using [semantic versioning](https://guide.esciencecenter.nl/#/best_practices/releases?id=semantic-versioning). -- For convenience, the package version is stored in a single place: `rcx-tk/pyproject.toml` under the `tool.bumpversion` header. -- Don't forget to update the version number before [making a release](https://guide.esciencecenter.nl/#/best_practices/releases)! - -## Logging - -- We recommend using the logging module for getting useful information from your module (instead of using print). -- The project is set up with a logging example. -- [Relevant section in the guide](https://guide.esciencecenter.nl/#/best_practices/language_guides/python?id=logging) +- Releases are labelled using the [semantic versioning](https://guide.esciencecenter.nl/#/best_practices/releases?id=semantic-versioning). ## CHANGELOG.md -- Document changes to your software package -- [Relevant section in the guide](https://guide.esciencecenter.nl/#/best_practices/releases?id=changelogmd) - -## CITATION.cff - -- To allow others to cite your software, add a `CITATION.cff` file -- It only makes sense to do this once there is something to cite (e.g., a software release with a DOI). -- Follow the [making software citable](https://guide.esciencecenter.nl/#/citable_software/making_software_citable) section in the guide. - -## CODE_OF_CONDUCT.md - -- Information about how to behave professionally -- [Relevant section in the guide](https://guide.esciencecenter.nl/#/best_practices/documentation?id=code-of-conduct) - -## CONTRIBUTING.md - -- Information about how to contribute to this software package -- [Relevant section in the guide](https://guide.esciencecenter.nl/#/best_practices/documentation?id=contribution-guidelines) - -## MANIFEST.in - -- List non-Python files that should be included in a source distribution -- [Relevant section in the guide](https://guide.esciencecenter.nl/#/best_practices/language_guides/python?id=building-and-packaging-code) - -## NOTICE - -- List of attributions of this project and Apache-license dependencies -- [Relevant section in the guide](https://guide.esciencecenter.nl/#/best_practices/licensing?id=notice) +- To document the changes, we use the [CHANGELOG.md](https://github.com/RECETOX/rcx-tk/blob/master/CHANGELOG.md) From 00eef7c54b50575cf8091ea29e4503a87192f610 Mon Sep 17 00:00:00 2001 From: KristinaGomoryova Date: Mon, 15 Jul 2024 11:01:08 +0200 Subject: [PATCH 08/23] readme updated --- README.dev.md | 33 +++++++++++++++++++-------------- README.md | 6 +++++- 2 files changed, 24 insertions(+), 15 deletions(-) diff --git a/README.dev.md b/README.dev.md index 9969d4f..3dde70d 100644 --- a/README.dev.md +++ b/README.dev.md @@ -2,26 +2,31 @@ If you're looking for user documentation, go [here](README.md). -## Development install +## Package installation -```shell -# Create a virtual environment, e.g. with -python -m venv env +To create a new environment, use the micromamba: + +```console +micromamba create rcx-tk +micromamba activate rcx-tk +``` +To install all dependencies specified in the `pyproject.toml` file, use poetry: -# activate virtual environment -source env/bin/activate +```console +poetry install +``` -# make sure to have a recent version of pip and setuptools -python -m pip install --upgrade pip setuptools +A command line interface was also implemented using Click, so the package can be run by either using python3: -# (from the project root directory) -# install rcx_tk as an editable package -python -m pip install --no-cache-dir --editable . -# install development dependencies -python -m pip install --no-cache-dir --editable .[dev] +```console +python3 --method='' ``` -Afterwards check that the install directory is present in the `PATH` environment variable. +or using poetry: + +```console +poetry run rcx_tk --method='' +``` ## Running the tests diff --git a/README.md b/README.md index ff29a71..b812217 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,11 @@ cd rcx-tk python -m pip install . ``` -Upon installation, the tool can be run also using the poetry: +Upon installation, the tool can be run also using either the python3 or poetry: + +```console +python3 --method='' +``` ```console poetry run rcx_tk --method='' From d4e88b644c6ec02ff6e474f0f0108e7250f50861 Mon Sep 17 00:00:00 2001 From: KristinaGomoryova Date: Mon, 15 Jul 2024 11:05:23 +0200 Subject: [PATCH 09/23] readme updated --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index b812217..b1886e4 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,9 @@ cd rcx-tk python -m pip install . ``` -Upon installation, the tool can be run also using either the python3 or poetry: +The main functions are process_metadata_file and process_alkane_ri_file. + +The tool can be run also using command-line interface, either by the python3 or poetry: ```console python3 --method='' @@ -49,8 +51,6 @@ python3 --method='' ``` - - ## Documentation The project is documented [here](https://rcx-tk.readthedocs.io/en/latest/?badge=latest). From 10706d0e83e1bc3a8fa3652066c07b1144f594c8 Mon Sep 17 00:00:00 2001 From: KristinaGomoryova Date: Mon, 15 Jul 2024 13:31:50 +0200 Subject: [PATCH 10/23] bump versions using poetry --- pyproject.toml | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 20272be..c416b25 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -117,17 +117,11 @@ known-first-party = ["rcx_tk"] force-single-line = true no-lines-before = ["future","standard-library","third-party","first-party","local-folder"] -[[tool.bumpversion.files]] -filename = "src/rcx_tk/__init__.py" - -[[tool.bumpversion.files]] -filename = "pyproject.toml" - -[[tool.bumpversion.files]] -filename = "CITATION.cff" - -[[tool.bumpversion.files]] -filename = "docs/conf.py" - [tool.poetry.scripts] rcx_tk = "rcx_tk.__main__:main" + +[tool.poetry_bumpversion.file."src/rcx_tk/__init__.py"] +[tool.poetry_bumpversion.file."CITATION.cff"] +[tool.poetry_bumpversion.file."docs/conf.py"] +[tool.poetry_bumpversion.file."pyproject.toml"] + From a51265d5d681f3d17949474474925197e5fadec3 Mon Sep 17 00:00:00 2001 From: KristinaGomoryova Date: Mon, 15 Jul 2024 13:40:36 +0200 Subject: [PATCH 11/23] readme.dev updated --- README.dev.md | 169 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 166 insertions(+), 3 deletions(-) diff --git a/README.dev.md b/README.dev.md index 3dde70d..321f6bb 100644 --- a/README.dev.md +++ b/README.dev.md @@ -7,7 +7,7 @@ If you're looking for user documentation, go [here](README.md). To create a new environment, use the micromamba: ```console -micromamba create rcx-tk +micromamba create -n rcx-tk poetry micromamba activate rcx-tk ``` To install all dependencies specified in the `pyproject.toml` file, use poetry: @@ -30,8 +30,171 @@ poetry run rcx_tk --method='' (don't forget to update links at bottom of page) +2. Verify that the information in [`CITATION.cff`](CITATION.cff) is correct. +3. Make sure the [version has been updated](#versioning). +4. Run the unit tests with `pytest -v` + +### (2/3) PyPI + +In a new terminal: + +```shell +# OPTIONAL: prepare a new directory with fresh git clone to ensure the release +# has the state of origin/main branch +cd $(mktemp -d rcx_tk.XXXXXX) +git clone git@github.com:RECETOX/rcx-tk . + +# make sure to have a recent version of pip and the publishing dependencies +python -m pip install --upgrade pip +python -m pip install .[publishing] + +# create the source distribution and the wheel +python -m build + +# upload to test pypi instance (requires credentials) +python -m twine upload --repository testpypi dist/* +``` + +Visit +[https://test.pypi.org/project/rcx_tk](https://test.pypi.org/project/rcx_tk) +and verify that your package was uploaded successfully. Keep the terminal open, we'll need it later. + +In a new terminal, without an activated virtual environment or an env directory: + +```shell +cd $(mktemp -d rcx_tk-test.XXXXXX) + +# prepare a clean virtual environment and activate it + +micromamba create rcx-tk-pypi +micromamba activate rcx-tk-pypi + +# make sure to have a recent version of pip and setuptools +python -m pip install --upgrade pip + +# install from test pypi instance: +python -m pip -v install --no-cache-dir \ +--index-url https://test.pypi.org/simple/ \ +--extra-index-url https://pypi.org/simple rcx_tk +``` + +Check that the package works as it should when installed from pypitest. + +Then upload to pypi.org with: + +```shell +# Back to the first terminal, +# FINAL STEP: upload to PyPI (requires credentials) +python -m twine upload dist/* +``` + +### (3/3) GitHub + +Don't forget to also make a [release on GitHub](https://github.com/RECETOX/rcx-tk/releases/new). If your repository uses the GitHub-Zenodo integration this will also trigger Zenodo into making a snapshot of your repository and sticking a DOI on it. \ No newline at end of file From 7a4415a3b79d8bbf0ded3bbe0d1394d780e81767 Mon Sep 17 00:00:00 2001 From: KristinaGomoryova Date: Mon, 15 Jul 2024 13:56:07 +0200 Subject: [PATCH 12/23] readme.dev updated --- README.dev.md | 48 +++++++++++++++++------------------------------- 1 file changed, 17 insertions(+), 31 deletions(-) diff --git a/README.dev.md b/README.dev.md index 321f6bb..8ab60dd 100644 --- a/README.dev.md +++ b/README.dev.md @@ -150,49 +150,35 @@ In a new terminal: # has the state of origin/main branch cd $(mktemp -d rcx_tk.XXXXXX) git clone git@github.com:RECETOX/rcx-tk . +``` -# make sure to have a recent version of pip and the publishing dependencies -python -m pip install --upgrade pip -python -m pip install .[publishing] - -# create the source distribution and the wheel -python -m build +Create and activate a new environment: -# upload to test pypi instance (requires credentials) -python -m twine upload --repository testpypi dist/* +```console +micromamba create rcx-tk-pypi +micromamba activate rcx-tk-pypi ``` -Visit -[https://test.pypi.org/project/rcx_tk](https://test.pypi.org/project/rcx_tk) -and verify that your package was uploaded successfully. Keep the terminal open, we'll need it later. - -In a new terminal, without an activated virtual environment or an env directory: +Create an account on PypI. -```shell -cd $(mktemp -d rcx_tk-test.XXXXXX) +In the Account settings, find the API tokens section and click on "Add API token". Copy your token. -# prepare a clean virtual environment and activate it +Add your API token to Poetry: -micromamba create rcx-tk-pypi -micromamba activate rcx-tk-pypi +```console +poetry config pypi-token.pypi your-api-token +``` -# make sure to have a recent version of pip and setuptools -python -m pip install --upgrade pip +Build your project: -# install from test pypi instance: -python -m pip -v install --no-cache-dir \ ---index-url https://test.pypi.org/simple/ \ ---extra-index-url https://pypi.org/simple rcx_tk +```console +poetry build ``` -Check that the package works as it should when installed from pypitest. +Publish your package to PyPI: -Then upload to pypi.org with: - -```shell -# Back to the first terminal, -# FINAL STEP: upload to PyPI (requires credentials) -python -m twine upload dist/* +```console +poetry publish ``` ### (3/3) GitHub From f8b9458756ceaf9dbf102c7d31225c3eeb2866c6 Mon Sep 17 00:00:00 2001 From: KristinaGomoryova Date: Mon, 15 Jul 2024 13:57:13 +0200 Subject: [PATCH 13/23] poetry install corrected --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b1886e4..904c97e 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ To install rcx_tk from GitHub repository, do: ```console git clone git@github.com:RECETOX/rcx-tk.git cd rcx-tk -python -m pip install . +poetry install ``` The main functions are process_metadata_file and process_alkane_ri_file. From 93c23a3baa961ce16a91e8ea287790abe31e7af1 Mon Sep 17 00:00:00 2001 From: KristinaGomoryova Date: Mon, 15 Jul 2024 14:03:21 +0200 Subject: [PATCH 14/23] project setup description returned --- project_setup.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/project_setup.md b/project_setup.md index 4bc61bb..608ecb0 100644 --- a/project_setup.md +++ b/project_setup.md @@ -1,5 +1,12 @@ # Project Setup +Here we provide some details about the project setup. Most of the choices are explained in the +[guide](https://guide.esciencecenter.nl). Links to the relevant sections are included below. Feel free to remove this +text when the development of the software package takes off. + +For a quick reference on software development, we refer to [the software guide +checklist](https://guide.esciencecenter.nl/#/best_practices/checklist). + ## Python versions This repository is set up with Python versions: From 666045d1ac83286cb97b3fa49029ca74e46b488a Mon Sep 17 00:00:00 2001 From: KristinaGomoryova Date: Mon, 15 Jul 2024 14:04:13 +0200 Subject: [PATCH 15/23] python versions corrected --- project_setup.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/project_setup.md b/project_setup.md index 608ecb0..f546476 100644 --- a/project_setup.md +++ b/project_setup.md @@ -14,6 +14,10 @@ This repository is set up with Python versions: - 3.11 - 3.12 +Add or remove Python versions based on project requirements. See [the +guide](https://guide.esciencecenter.nl/#/best_practices/language_guides/python) for more information about Python +versions. + ## Package management and dependencies For installing the dependencies and package management, [micromamba](https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html) and [poetry](https://python-poetry.org/) have been used. From a03f3129413a589f79eeba5ab0711cd53070390b Mon Sep 17 00:00:00 2001 From: KristinaGomoryova Date: Mon, 15 Jul 2024 14:05:15 +0200 Subject: [PATCH 16/23] micromamba create updated for poetry --- project_setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/project_setup.md b/project_setup.md index f546476..6a81dea 100644 --- a/project_setup.md +++ b/project_setup.md @@ -29,7 +29,7 @@ The dependencies are listed in the `pyproject.toml` file under the section `[too To create a new environment, use the micromamba: ```console -micromamba create rcx-tk +micromamba create -n rcx-tk poetry micromamba activate rcx-tk ``` To install all dependencies specified in the `pyproject.toml` file, use poetry: From a11796687c7d8e8aeb5749da2453d4ff88ead4b8 Mon Sep 17 00:00:00 2001 From: KristinaGomoryova Date: Mon, 15 Jul 2024 14:06:21 +0200 Subject: [PATCH 17/23] tests reverted --- project_setup.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/project_setup.md b/project_setup.md index 6a81dea..2443296 100644 --- a/project_setup.md +++ b/project_setup.md @@ -40,9 +40,16 @@ poetry install ## Testing and code coverage -- Tests are in the `tests` folder, in the `test_process_metadata_file.py` file. +- Tests should be put in the `tests` folder. +- The `tests` folder contains: + - Example tests that you should replace with your own meaningful tests (file: `test_my_module.py`) - The testing framework used is [PyTest](https://pytest.org) + - [PyTest introduction](https://pythontest.com/pytest-book/) + - PyTest is listed as a development dependency + - This is configured in `pyproject.toml` - The project uses [GitHub action workflows](https://docs.github.com/en/actions) to automatically run tests on GitHub infrastructure against multiple Python versions + - Workflows can be found in [`.github/workflows`](.github/workflows/) +- [Relevant section in the guide](https://guide.esciencecenter.nl/#/best_practices/language_guides/python?id=testing) ## Documentation From 2409d82ae0e152e87cba1d931b138032615c6595 Mon Sep 17 00:00:00 2001 From: KristinaGomoryova Date: Mon, 15 Jul 2024 14:07:29 +0200 Subject: [PATCH 18/23] documentation reverted --- project_setup.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/project_setup.md b/project_setup.md index 2443296..9d52377 100644 --- a/project_setup.md +++ b/project_setup.md @@ -53,10 +53,19 @@ poetry install ## Documentation -- Documentation is in the [`docs/`](docs/) directory. The contents have been generated using `sphinx-quickstart` (Sphinx version 1.6.5). +- Documentation should be put in the [`docs/`](docs/) directory. The contents have been generated using `sphinx-quickstart` (Sphinx version 1.6.5). +- We recommend writing the documentation using Restructured Text (reST) and Google style docstrings. + - [Restructured Text (reST) and Sphinx CheatSheet](https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html) + - [Google style docstring examples](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html). - The documentation is set up with the ReadTheDocs Sphinx theme. + - Check out its [configuration options](https://sphinx-rtd-theme.readthedocs.io/en/latest/). - [AutoAPI](https://sphinx-autoapi.readthedocs.io/) is used to generate documentation for the package Python objects. - `.readthedocs.yaml` is the ReadTheDocs configuration file. When ReadTheDocs is building the documentation this package and its development dependencies are installed so the API reference can be rendered. +- [Relevant section in the guide](https://guide.esciencecenter.nl/#/best_practices/language_guides/python?id=writingdocumentation) + +## Coding style conventions and code quality + +- [Relevant section in the NLeSC guide](https://guide.esciencecenter.nl/#/best_practices/language_guides/python?id=coding-style-conventions) and [README.dev.md](README.dev.md). ## Continuous code quality From 443f497cb787d9edf4a5f230698d4fcb43248ce0 Mon Sep 17 00:00:00 2001 From: KristinaGomoryova Date: Mon, 15 Jul 2024 14:08:52 +0200 Subject: [PATCH 19/23] versioning to notice reverted --- project_setup.md | 39 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 37 insertions(+), 2 deletions(-) diff --git a/project_setup.md b/project_setup.md index 9d52377..ea20020 100644 --- a/project_setup.md +++ b/project_setup.md @@ -76,8 +76,43 @@ poetry install ## Package version number -- Releases are labelled using the [semantic versioning](https://guide.esciencecenter.nl/#/best_practices/releases?id=semantic-versioning). +- We recommend using [semantic versioning](https://guide.esciencecenter.nl/#/best_practices/releases?id=semantic-versioning). +- For convenience, the package version is stored in a single place: `rcx-tk/pyproject.toml` under the `tool.bumpversion` header. +- Don't forget to update the version number before [making a release](https://guide.esciencecenter.nl/#/best_practices/releases)! + +## Logging + +- We recommend using the logging module for getting useful information from your module (instead of using print). +- The project is set up with a logging example. +- [Relevant section in the guide](https://guide.esciencecenter.nl/#/best_practices/language_guides/python?id=logging) ## CHANGELOG.md -- To document the changes, we use the [CHANGELOG.md](https://github.com/RECETOX/rcx-tk/blob/master/CHANGELOG.md) +- Document changes to your software package +- [Relevant section in the guide](https://guide.esciencecenter.nl/#/best_practices/releases?id=changelogmd) + +## CITATION.cff + +- To allow others to cite your software, add a `CITATION.cff` file +- It only makes sense to do this once there is something to cite (e.g., a software release with a DOI). +- Follow the [making software citable](https://guide.esciencecenter.nl/#/citable_software/making_software_citable) section in the guide. + +## CODE_OF_CONDUCT.md + +- Information about how to behave professionally +- [Relevant section in the guide](https://guide.esciencecenter.nl/#/best_practices/documentation?id=code-of-conduct) + +## CONTRIBUTING.md + +- Information about how to contribute to this software package +- [Relevant section in the guide](https://guide.esciencecenter.nl/#/best_practices/documentation?id=contribution-guidelines) + +## MANIFEST.in + +- List non-Python files that should be included in a source distribution +- [Relevant section in the guide](https://guide.esciencecenter.nl/#/best_practices/language_guides/python?id=building-and-packaging-code) + +## NOTICE + +- List of attributions of this project and Apache-license dependencies +- [Relevant section in the guide](https://guide.esciencecenter.nl/#/best_practices/licensing?id=notice) \ No newline at end of file From 2e7f1617d1280208cf3711a09e998af67f255bab Mon Sep 17 00:00:00 2001 From: KristinaGomoryova Date: Mon, 15 Jul 2024 14:11:20 +0200 Subject: [PATCH 20/23] micromamba create updated --- README.dev.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.dev.md b/README.dev.md index 8ab60dd..d395950 100644 --- a/README.dev.md +++ b/README.dev.md @@ -155,7 +155,7 @@ git clone git@github.com:RECETOX/rcx-tk . Create and activate a new environment: ```console -micromamba create rcx-tk-pypi +micromamba create -n rcx-tk-pypi poetry micromamba activate rcx-tk-pypi ``` From f87b5a1b5ef0247d9394ece301ed310a4e95df3a Mon Sep 17 00:00:00 2001 From: KristinaGomoryova Date: Mon, 15 Jul 2024 14:15:27 +0200 Subject: [PATCH 21/23] orcid changed back because failing --- CITATION.cff | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CITATION.cff b/CITATION.cff index 9b562a0..1045ff0 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -6,7 +6,7 @@ authors: - family-names: Ahmad given-names: Zargham - orcid: "" + orcid: "https://orcid.org/0000-0000-0000-0000" date-released: 2024-06-19 version: "0.1.0" repository-code: "https://github.com/RECETOX/rcx-tk" From 92caff00f3ace9c3114d63acdb4bd5183a28f572 Mon Sep 17 00:00:00 2001 From: Helge Hecht Date: Mon, 15 Jul 2024 12:20:49 +0000 Subject: [PATCH 22/23] Update README.dev.md --- README.dev.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.dev.md b/README.dev.md index d395950..a28d3b6 100644 --- a/README.dev.md +++ b/README.dev.md @@ -19,7 +19,7 @@ poetry install A command line interface was also implemented using Click, so the package can be run by either using python3: ```console -python3 --method='' +python3 -m rcx_tk --method='' ``` or using poetry: From 71dc77420a2a71c0b90aa5d063d9c3bfab8e5f0e Mon Sep 17 00:00:00 2001 From: Helge Hecht Date: Mon, 15 Jul 2024 12:20:54 +0000 Subject: [PATCH 23/23] Update README.dev.md --- README.dev.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.dev.md b/README.dev.md index a28d3b6..4c401f0 100644 --- a/README.dev.md +++ b/README.dev.md @@ -159,7 +159,7 @@ micromamba create -n rcx-tk-pypi poetry micromamba activate rcx-tk-pypi ``` -Create an account on PypI. +Create an account on PyPI. In the Account settings, find the API tokens section and click on "Add API token". Copy your token.