Metadata-Version: 2.4
Name: cnb-tools
Version: 0.4.2
Summary: Convenience tools/functions for challenges and benchmarking on Synapse.org
Project-URL: Repository, https://github.com/Sage-Bionetworks-Challenges/cnb-tools
Project-URL: Documentation, https://sage-bionetworks-challenges.github.io/cnb-tools
Project-URL: Bug Tracker, https://github.com/Sage-Bionetworks-Challenges/cnb-tools/issues
Author-email: Sage CNB Team <cnb@sagebase.org>
Maintainer-email: Verena Chung <verena.chung@sagebase.org>
License: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.14,>=3.10
Requires-Dist: click<8.2.0,>=8.0.0
Requires-Dist: pandas>=2.0.3
Requires-Dist: synapseclient>=4.7.0
Requires-Dist: typer>=0.9.0
Description-Content-Type: text/markdown

<div align="center">

  ![cnb-tools](https://raw.githubusercontent.com/Sage-Bionetworks-Challenges/cnb-tools/main/docs/assets/cnb-tools.png)

  <h3>
    Convenience tools/functions for challenges and benchmarking on
    <a href="https://www.synapse.org" title="Synapse.org">Synapse.org</a>
  </h3>

  <br/>

  <a href="https://pypi.org/project/cnb-tools/" title="cnb-tools on PyPI">
    <img alt="PyPI version" src="https://img.shields.io/pypi/v/cnb-tools?style=flat-square&logo=pypi&logoColor=white&color=%23679EC1">
  </a>
  <img alt="Supported Python versions" src="https://img.shields.io/badge/python-3.10 | 3.11 | 3.12 | 3.13-%23EB8231?style=flat-square&logo=python&logoColor=white">
  <a href="https://github.com/Sage-Bionetworks-Challenges/cnb-tools/blob/main/LICENSE" title="License">
    <img alt="License" src="https://img.shields.io/github/license/Sage-Bionetworks-Challenges/cnb-tools?style=flat-square&logo=github&color=%236DB56D">
  </a>

</div>

---

📖 **Documentation**: [https://sage-bionetworks-challenges.github.io/cnb-tools]

👾 **Source code**: [https://github.com/Sage-Bionetworks-Challenges/cnb-tools]

---

**cnb-tools** is a set of tools and commands that provides an interface
for managing crowd-sourced challenges hosted on Synapse.org, including
but not limited to, [DREAM Challenges].

## Requirements

- [Python 3.10+]
- [Synapse account]

To fully utilize **cnb-tools**, you must have a Synapse account and
provide your credentials to the tool. First, generate a Synapse
[Personal Access Token (PAT)] with all token permissions enabled.

Next, run the following command, then follow the prompts to enter
your Synapse username and PAT:

```console
synapse config
```

This will create a `.synapseConfig` file in your home directory. For
security, we recommend updating its permissions so that other users
on your machine do not have read access to your credentials, e.g.

```console
chmod 600 ~/.synapseConfig
```

## Installation

For best practice, use a Python environment to install **cnb-tools**
rather than directly into your base env. In our docs, we will be
using [uv], but you can use [venv], [pyenv], etc.

```console
# Create a new env and activate it
uv venv --python 3.12 .venv
source .venv/bin/activate

# Install cnb-tools
uv pip install cnb-tools
```

> ⓘ **NOTE**
>
> **cnb-tools** builds off of the Synapse Python Client — by
> installing **cnb-tools**, you will also be installing **synapseclient**.
>  
> → [Read its docs.]

Verify the installation with:

```console
cnb-tools
```

## Running With Docker

If you rather not install `cnb-tools` onto your machine, you may still use it
via Docker!  The package and list of versions are [available here].

To provide your Synapse credentials to the Docker container, you must first
create a file with your Synapse PAT as the `SYNAPSE_AUTH_TOKEN` environment
variable:

```yaml
SYNAPSE_AUTH_TOKEN=<YOUR PAT>
```

The `docker run` command will look something like this, assuming the file is
named `~/.synapse-config`:

```console
docker run --rm \
  --env-file ~/.synapse-config \
  ghcr.io/sage-bionetworks-challenges/cnb-tools \
  COMMAND [ARGS]
```

## License

**cnb-tools** is released under the Apache 2.0 license.

[https://sage-bionetworks-challenges.github.io/cnb-tools]: https://sage-bionetworks-challenges.github.io/cnb-tools
[https://github.com/Sage-Bionetworks-Challenges/cnb-tools]: https://github.com/Sage-Bionetworks-Challenges/cnb-tools
[DREAM Challenges]: https://dreamchallenges.org/
[Python 3.10+]: https://www.python.org/downloads/
[Synapse account]: https://www.synapse.org/#!LoginPlace:0
[Personal Access Token (PAT)]: https://www.synapse.org/#!PersonalAccessTokens:
[uv]: https://docs.astral.sh/uv/
[venv]: https://docs.python.org/3/library/venv.html
[pyenv]: https://github.com/pyenv/pyenv
[Read its docs.]: https://python-docs.synapse.org/
[available here]: https://github.com/Sage-Bionetworks-Challenges/cnb-tools/pkgs/container/cnb-tools
