diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 00000000..6cd016a1 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,12 @@ +# To get started with Dependabot version updates, you'll need to specify which +# package ecosystems to update and where the package manifests are located. +# Please see the documentation for all configuration options: +# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates + +version: 2 +updates: + + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 81cef792..a0e1419b 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -36,7 +36,7 @@ jobs: # We pin the commit hash corresponding to v0.5.0, and not pinning the tag # because we are giving full access through the github.token. - name: Cancel Previous Runs - uses: styfle/cancel-workflow-action@148d9a848c6acaf90a3ec30bc5062f646f8a4163 + uses: styfle/cancel-workflow-action@0.12.1 with: access_token: ${{ github.token }} @@ -137,7 +137,7 @@ jobs: path: doc/_build/html - name: Checkout the gh-pages branch in a separate folder - uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f + uses: actions/checkout@v3 with: ref: gh-pages # Checkout to this folder instead of the current one diff --git a/.github/workflows/pypi.yml b/.github/workflows/pypi.yml index 11fb69d9..59ee0d5f 100644 --- a/.github/workflows/pypi.yml +++ b/.github/workflows/pypi.yml @@ -110,7 +110,7 @@ jobs: - name: Publish to Test PyPI # Only publish to TestPyPI when a PR is merged (pushed to main) if: success() && github.event_name == 'push' - uses: pypa/gh-action-pypi-publish@bce3b74dbf8cc32833ffba9d15f83425c1a736e0 + uses: pypa/gh-action-pypi-publish@v1.8.11 with: user: __token__ password: ${{ secrets.TEST_PYPI_TOKEN}} @@ -122,7 +122,7 @@ jobs: - name: Publish to PyPI # Only publish to PyPI when a release triggers the build if: success() && github.event_name == 'release' - uses: pypa/gh-action-pypi-publish@bce3b74dbf8cc32833ffba9d15f83425c1a736e0 + uses: pypa/gh-action-pypi-publish@v1.8.11 with: user: __token__ password: ${{ secrets.PYPI_TOKEN}} diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 83632a10..956308c1 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -17,10 +17,6 @@ on: release: types: - published - schedule: - # Run every Monday at 12:00 UTC - # * is a special character in YAML so you have to quote this string - - cron: "00 12 * * 1" # Use bash by default in all jobs defaults: @@ -43,13 +39,17 @@ jobs: - ubuntu - macos - windows - python: - - "3.7" - - "3.11" dependencies: + - oldest - latest - optional - - oldest + include: + - dependencies: oldest + python: "3.7" + - dependencies: latest + python: "3.11" + - dependencies: optional + python: "3.11" env: REQUIREMENTS: env/requirements-build.txt env/requirements-test.txt # Used to tag codecov submissions @@ -62,7 +62,7 @@ jobs: # We pin the commit hash corresponding to v0.5.0, and not pinning the tag # because we are giving full access through the github.token. - name: Cancel Previous Runs - uses: styfle/cancel-workflow-action@148d9a848c6acaf90a3ec30bc5062f646f8a4163 + uses: styfle/cancel-workflow-action@0.12.1 with: access_token: ${{ github.token }} diff --git a/README.md b/README.md index 806990a4..9d579142 100644 --- a/README.md +++ b/README.md @@ -21,35 +21,41 @@ Part of the Fatiando a Terra ## About -*Does your Python package include sample datasets? -Are you shipping them with the code? -Are they getting too big?* +> Just want to download a file without messing with `requests` and `urllib`? +> Trying to add sample datasets to your Python package? +> **Pooch is here to help!** -**Pooch** is here to help! It will manage a data *registry* by downloading your -data files from a server only when needed and storing them locally in a data -*cache* (a folder on your computer). - -Here are Pooch's main features: +*Pooch* is a **Python library** that can manage data by **downloading files** +from a server (only when needed) and storing them locally in a data **cache** +(a folder on your computer). * Pure Python and minimal dependencies. -* Download a file only if necessary (it's not in the data cache or needs to be - updated). -* Verify download integrity through SHA256 hashes (also used to check if a file - needs to be updated). -* Designed to be extended: plug in custom download (FTP, scp, etc) and - post-processing (unzip, decompress, rename) functions. -* Includes utilities to unzip/decompress the data upon download to save loading - time. -* Can handle basic HTTP authentication (for servers that require a login) and - printing download progress bars. -* Easily set up an environment variable to overwrite the data cache location. - -*Are you a scientist or researcher? Pooch can help you too!* - -* Automatically download your data files so you don't have to keep them in your - GitHub repository. -* Make sure everyone running the code has the same version of the data files - (enforced through the SHA256 hashes). +* Download files over HTTP, FTP, and from data repositories like Zenodo and figshare. +* Built-in post-processors to unzip/decompress the data after download. +* Designed to be extended: create custom downloaders and post-processors. + +Are you a **scientist** or researcher? Pooch can help you too! + +* Host your data on a repository and download using the DOI. +* Automatically download data using code instead of telling colleagues to do it themselves. +* Make sure everyone running the code has the same version of the data files. + +## Projects using Pooch + +[SciPy](https://github.com/scipy/scipy), +[scikit-image](https://github.com/scikit-image/scikit-image), +[Ensaio](https://github.com/fatiando/ensaio), +[MetPy](https://github.com/Unidata/MetPy), +[napari](https://github.com/napari/napari), +[icepack](https://github.com/icepack/icepack), +[histolab](https://github.com/histolab/histolab), +[seaborn-image](https://github.com/SarthakJariwala/seaborn-image), +[Open AR-Sandbox](https://github.com/cgre-aachen/open_AR_Sandbox), +[climlab](https://github.com/climlab/climlab), +[mne-python](https://github.com/mne-tools/mne-python), +[GemGIS](https://github.com/cgre-aachen/gemgis) + +> If you're using Pooch, **send us a pull request** adding your project to the list. ## Example @@ -136,23 +142,6 @@ def fetch_gravity_data(): return data ``` -## Projects using Pooch - -* [SciPy](https://github.com/scipy/scipy) -* [scikit-image](https://github.com/scikit-image/scikit-image) -* [MetPy](https://github.com/Unidata/MetPy) -* [icepack](https://github.com/icepack/icepack) -* [histolab](https://github.com/histolab/histolab) -* [seaborn-image](https://github.com/SarthakJariwala/seaborn-image) -* [Ensaio](https://github.com/fatiando/ensaio) -* [Open AR-Sandbox](https://github.com/cgre-aachen/open_AR_Sandbox) -* [climlab](https://github.com/climlab/climlab) -* [napari](https://github.com/napari/napari) -* [mne-python](https://github.com/mne-tools/mne-python) -* [GemGIS](https://github.com/cgre-aachen/gemgis) - -*If you're using Pooch, send us a pull request adding your project to the list.* - ## Getting involved 🗨️ **Contact us:** diff --git a/doc/_static/favicon.png b/doc/_static/favicon.png index d03ecee2..3c960be3 100644 Binary files a/doc/_static/favicon.png and b/doc/_static/favicon.png differ diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html index 50fde1fa..0b486cf0 100644 --- a/doc/_templates/layout.html +++ b/doc/_templates/layout.html @@ -8,7 +8,7 @@ {% block htmltitle %} - {% if title == '' or title == 'Home' %} + {% if title == '' or 'no title' in title or title == 'Home' %} {{ docstitle|striptags|e }} {% else %} {{ title|striptags|e }} | {{ docstitle|striptags|e }} diff --git a/doc/about.rst b/doc/about.rst index 1969234c..72d37def 100644 --- a/doc/about.rst +++ b/doc/about.rst @@ -6,42 +6,43 @@ Why use Pooch? Use cases --------- +.. tab-set:: -.. tabbed:: Just download a file + .. tab-item:: Just download a file - **Who**: Scientists/researchers/developers looking to simply download a - file. + **Who**: Scientists/researchers/developers looking to simply download a + file. - Pooch makes it easy to download a file (one function call). - On top of that, it also comes with some bonus features: + Pooch makes it easy to download a file (one function call). + On top of that, it also comes with some bonus features: - * Download and cache your data files locally (so it's only downloaded - once). - * Make sure everyone running the code has the same version of the data - files by verifying cryptographic hashes. - * Multiple download protocols HTTP/FTP/SFTP and basic authentication. - * Download from Digital Object Identifiers (DOIs) issued by repositories - like figshare and Zenodo. - * Built-in utilities to unzip/decompress files upon download + * Download and cache your data files locally (so it's only downloaded + once). + * Make sure everyone running the code has the same version of the data + files by verifying cryptographic hashes. + * Multiple download protocols HTTP/FTP/SFTP and basic authentication. + * Download from Digital Object Identifiers (DOIs) issued by repositories + like figshare and Zenodo. + * Built-in utilities to unzip/decompress files upon download - **Start here:** :ref:`retrieve` + **Start here:** :ref:`retrieve` -.. tabbed:: Use by another library + .. tab-item:: Manage sample data for a Python program - **Who**: Package developers wanting to include sample data for use in - tutorials and tests. + **Who**: Package developers wanting to include sample data for use in + tutorials and tests. - Pooch was designed for this! It offers: + Pooch was designed for this! It offers: - * Pure Python and :ref:`minimal dependencies `. - * Download a file only if necessary. - * Verification of download integrity through cryptographic hashes. - * Extensible design: plug in custom download and post-processing functions. - * Built-in utilities to unzip/decompress files upon download - * Multiple download protocols HTTP/FTP/SFTP and basic authentication. - * User control of data cache location through environment variables. + * Pure Python and :ref:`minimal dependencies `. + * Download a file only if necessary. + * Verification of download integrity through cryptographic hashes. + * Extensible design: plug in custom download and post-processing functions. + * Built-in utilities to unzip/decompress files upon download + * Multiple download protocols HTTP/FTP/SFTP and basic authentication. + * User control of data cache location through environment variables. - **Start here:** :ref:`intermediate` + **Start here:** :ref:`intermediate` History ------- diff --git a/doc/conf.py b/doc/conf.py index da2f10b4..6c7bb4de 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -32,16 +32,9 @@ "sphinx.ext.extlinks", "sphinx.ext.intersphinx", "sphinx.ext.napoleon", - "sphinx_panels", + "sphinx_design", ] -# Disable including boostrap CSS for sphinx_panels since it's already included -# with sphinx-book-theme -panels_add_bootstrap_css = False -panels_css_variables = { - "tabs-color-label-inactive": "hsla(231, 99%, 66%, 0.5)", -} - # Configuration to include links to other project docs when referencing # functions/classes intersphinx_mapping = { @@ -75,7 +68,9 @@ # ----------------------------------------------------------------------------- html_title = f'{project} {version}' html_short_title = project -html_logo = "_static/pooch-logo.png" +# Don't use the logo since it gets in the way of the project name and is +# repeated in the front page. +# html_logo = "_static/pooch-logo.png" html_favicon = "_static/favicon.png" html_last_updated_fmt = "%b %d, %Y" html_copy_source = True diff --git a/doc/index.rst b/doc/index.rst index 57b98fa5..f2306777 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,87 +1,114 @@ .. title:: Home -======== -|banner| -======== +.. raw:: html + +
+ +

Pooch

+

+ + A friend to fetch your data files + +

+
-.. |banner| image:: _static/readme-banner.png - :alt: Pooch Documentation - :align: middle .. raw:: html -

+

Just want to download a file without messing with requests and urllib? -
Trying to add sample datasets to your Python package? -
Pooch is here to help!

+*Pooch* is a **Python library** that can manage data by **downloading files** +from a server (only when needed) and storing them locally in a data **cache** +(a folder on your computer). + +* Pure Python and minimal dependencies. +* Download files over HTTP, FTP, and from data repositories like Zenodo and figshare. +* Built-in post-processors to unzip/decompress the data after download. +* Designed to be extended: create custom downloaders and post-processors. -.. panels:: - :header: text-center text-large - :card: border-1 m-1 text-center +Are you a **scientist** or researcher? Pooch can help you too! - **Getting started** - ^^^^^^^^^^^^^^^^^^^ +* Host your data on a repository and download using the DOI. +* Automatically download data using code instead of telling colleagues to do it themselves. +* Make sure everyone running the code has the same version of the data files. - New to Pooch? +---- - .. link-button:: about - :type: ref - :text: Start here - :classes: btn-outline-primary btn-block stretched-link +.. grid:: 1 2 1 2 + :margin: 5 5 0 0 + :padding: 0 0 0 0 + :gutter: 4 - --- + .. grid-item-card:: :octicon:`info` Getting started + :text-align: center + :class-title: sd-fs-5 + :class-card: sd-p-3 - **Need help?** - ^^^^^^^^^^^^^^ + New to Pooch? Start here! - Ask on our community channels + .. button-ref:: about + :ref-type: ref + :click-parent: + :color: primary + :outline: + :expand: - .. link-button:: https://www.fatiando.org/contact - :type: url - :text: Join the conversation - :classes: btn-outline-primary btn-block stretched-link + .. grid-item-card:: :octicon:`comment-discussion` Need help? + :text-align: center + :class-title: sd-fs-5 + :class-card: sd-p-3 - --- + Ask on our community channels. - **Reference documentation** - ^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. button-link:: https://www.fatiando.org/contact + :click-parent: + :color: primary + :outline: + :expand: - A list of our functions and classes + Join the conversation :octicon:`link-external` - .. link-button:: api - :type: ref - :text: API reference - :classes: btn-outline-primary btn-block stretched-link + .. grid-item-card:: :octicon:`file-badge` Reference documentation + :text-align: center + :class-title: sd-fs-5 + :class-card: sd-p-3 - --- + A list of modules and functions. - **Using Pooch for research?** - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. button-ref:: api + :ref-type: ref + :color: primary + :outline: + :expand: - Citations help support our work + .. grid-item-card:: :octicon:`bookmark` Using Pooch for research? + :text-align: center + :class-title: sd-fs-5 + :class-card: sd-p-3 - .. link-button:: citing - :type: ref - :text: Cite Pooch - :classes: btn-outline-primary btn-block stretched-link + Citations help support our work! + .. button-ref:: citing + :ref-type: ref + :color: primary + :outline: + :expand: + +---- .. seealso:: Pooch is a part of the `Fatiando a Terra `_ project. - -Table of contents ------------------ - .. toctree:: :caption: Getting Started + :hidden: :maxdepth: 1 about.rst @@ -92,6 +119,7 @@ Table of contents .. toctree:: :caption: Training your Pooch + :hidden: :maxdepth: 1 hashes.rst @@ -109,6 +137,7 @@ Table of contents .. toctree:: :caption: Reference + :hidden: :maxdepth: 1 api/index.rst @@ -119,6 +148,7 @@ Table of contents .. toctree:: :caption: Community + :hidden: Join the community Code of Conduct diff --git a/doc/install.rst b/doc/install.rst index fb00e1a8..4961ae12 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -5,31 +5,39 @@ Installing There are different ways to install Pooch: -.. tabbed:: pip +.. tab-set:: - Using the `pip `__ package manager: + .. tab-item:: pip - .. code:: bash + Using the `pip `__ package manager: - python -m pip install pooch + .. code:: bash -.. tabbed:: conda + python -m pip install pooch - Using the `conda `__ package manager that comes with the - Anaconda/Miniconda distribution: + .. tab-item:: conda/mamba - .. code:: bash + Using the `conda `__ or mamba package manager that + comes with the Anaconda/Miniconda/Miniforge distributions: - conda install pooch --channel conda-forge + .. code:: bash -.. tabbed:: Development version + conda install pooch --channel conda-forge - Using ``pip`` to install the latest **unreleased** version from GitHub - (**not recommended** in most situations): + or - .. code:: bash + .. code:: bash - python -m pip install --upgrade git+https://github.com/fatiando/pooch + mamba install pooch --channel conda-forge + + .. tab-item:: Development version + + Using ``pip`` to install the latest **unreleased** version from GitHub + (**not recommended** in most situations): + + .. code:: bash + + python -m pip install --upgrade git+https://github.com/fatiando/pooch .. note:: diff --git a/env/requirements-docs.txt b/env/requirements-docs.txt index c3099316..adc9427a 100644 --- a/env/requirements-docs.txt +++ b/env/requirements-docs.txt @@ -1,4 +1,4 @@ # Documentation requirements -sphinx==4.4.* -sphinx-book-theme==0.2.* -sphinx-panels==0.6.* +sphinx==7.2.* +sphinx-book-theme==1.1.* +sphinx-design==0.5.* diff --git a/environment.yml b/environment.yml index 0dd03145..0855c00d 100644 --- a/environment.yml +++ b/environment.yml @@ -18,9 +18,9 @@ dependencies: - pytest-httpserver - coverage # Documentation - - sphinx==4.4.* - - sphinx-book-theme==0.2.* - - sphinx-panels==0.6.* + - sphinx==7.2.* + - sphinx-book-theme==1.1.* + - sphinx-design==0.5.* # Style - pathspec - black>=20.8b1 diff --git a/pooch/downloaders.py b/pooch/downloaders.py index e34a5890..32a2090b 100644 --- a/pooch/downloaders.py +++ b/pooch/downloaders.py @@ -1137,6 +1137,6 @@ def populate_registry(self, pooch): """ for filedata in self.api_response.json()["data"]["latestVersion"]["files"]: - pooch.registry[ - filedata["dataFile"]["filename"] - ] = f"md5:{filedata['dataFile']['md5']}" + pooch.registry[filedata["dataFile"]["filename"]] = ( + f"md5:{filedata['dataFile']['md5']}" + )