Skip to main content
Pooch

Documentation | Documentation (dev version) | Contact | Part of the Fatiando a Terra project

Latest version on PyPI Latest version on conda-forge TravisCI build status Azure Pipelines build status Test coverage status Compatible Python versions.

🚨🚨 Pooch v0.6.0 is the last release to support Python 2.7 🚨🚨

TL;DR

"""
Module mypackage/datasets.py
"""
import pooch

# Get the version string from your project. You have one of these, right?
from . import version


# Create a new friend to manage your sample data storage
GOODBOY = pooch.create(
    # Folder where the data will be stored. For a sensible default, use the default
    # cache folder for your OS.
    path=pooch.os_cache("mypackage"),
    # Base URL of the remote data store. Will call .format on this string to insert
    # the version (see below).
    base_url="https://github.com/myproject/mypackage/raw/{version}/data/",
    # Pooches are versioned so that you can use multiple versions of a package
    # simultaneously. Use PEP440 compliant version number. The version will be
    # appended to the path.
    version=version,
    # If a version as a "+XX.XXXXX" suffix, we'll assume that this is a dev version
    # and replace the version with this string.
    version_dev="master",
    # An environment variable that overwrites the path.
    env="MYPACKAGE_DATA_DIR",
    # The cache file registry. A dictionary with all files managed by this pooch.
    # Keys are the file names (relative to *base_url*) and values are their
    # respective SHA256 hashes. Files will be downloaded automatically when needed
    # (see fetch_gravity_data).
    registry={"gravity-data.csv": "89y10phsdwhs09whljwc09whcowsdhcwodcy0dcuhw"}
)
# You can also load the registry from a file. Each line contains a file name and
# it's sha256 hash separated by a space. This makes it easier to manage large
# numbers of data files. The registry file should be in the same directory as this
# module.
GOODBOY.load_registry("registry.txt")


# Define functions that your users can call to get back some sample data in memory
def fetch_gravity_data():
    """
    Load some sample gravity data to use in your docs.
    """
    # Fetch the path to a file in the local storae. If it's not there, we'll
    # download it.
    fname = GOODBOY.fetch("gravity-data.csv")
    # Load it with numpy/pandas/etc
    data = ...
    return data

About

Does your Python package include sample datasets? Are you shipping them with the code? Are they getting too big?

Pooch will manage downloading your sample data files over HTTP from a server and storing them in a local directory:

  • Download a file only if it’s not in the local storage.

  • Check the SHA256 hash to make sure the file is not corrupted or needs updating.

  • If the hash is different from the registry, Pooch will download a new version of the file.

  • If the hash still doesn’t match, Pooch will raise an exception warning of possible data corruption.

Projects using Pooch

If you’re using Pooch, send us a pull request adding your project to the list.

Contacting Us

Citing Pooch

This is research software made by scientists (see AUTHORS.md). Citations help us justify the effort that goes into building and maintaining this project. If you used Pooch for your research, please consider citing us.

See our CITATION.rst file to find out more.

Contributing

Code of conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Contributing Guidelines

Please read our Contributing Guide to see how you can help and give feedback.

Imposter syndrome disclaimer

We want your help. No, really.

There may be a little voice inside your head that is telling you that you’re not ready to be an open source contributor; that your skills aren’t nearly good enough to contribute. What could you possibly offer?

We assure you that the little voice in your head is wrong.

Being a contributor doesn’t just mean writing code. Equality important contributions include: writing or proof-reading documentation, suggesting or implementing tests, or even giving feedback about the project (including giving feedback about the contribution process). If you’re coming to the project with fresh eyes, you might see the errors and assumptions that seasoned contributors have glossed over. If you can write any code at all, you can contribute code to open source. We are constantly trying out new skills, making mistakes, and learning from those mistakes. That’s how we all improve and we are happy to help others learn.

This disclaimer was adapted from the MetPy project.

License

This is free software: you can redistribute it and/or modify it under the terms of the BSD 3-clause License. A copy of this license is provided in LICENSE.txt.

Documentation for other versions

Metadata

Release files for pooch 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pooch 0.6.0
File Size Uploaded Provenance Actions
pooch-0.6.0.tar.gz 54.1 kB Without provenance Details for pooch-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pooch 0.6.0
File Interpreter ABI Platform Actions
pooch-0.6.0-py3-none-any.whl Python 3 none any Details for pooch-0.6.0-py3-none-any.whl

Total release size: 87.3 kB

Release files / pooch-0.6.0.tar.gz

Download URL pooch-0.6.0.tar.gz
Size 54.1 kB
Tags Source
SHA-256 checksum
How to use checksums
74c63d3da3cfbde60f70b2ce85aa137ff920614072ad0c6df181aab547cdb714
BLAKE2b-256 checksum
How to use checksums
0b4d421d17b796b7b2547a7dbfdf589d1406e7ae71742a0830dce5b6ccd04057
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/2.0.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.4.0 requests-toolbelt/0.9.1 tqdm/4.36.1 CPython/3.6.7

Release files / pooch-0.6.0-py3-none-any.whl

Download URL pooch-0.6.0-py3-none-any.whl
Size 33.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
23d0c28b0b40a6537c2453591d3e845ce1f7b4c6f6d52a95ecf5dfbcb6dc66d5
BLAKE2b-256 checksum
How to use checksums
9a1bc2bbb05710b3cc209adb63e66efe3baa6605299bed479a5176c9487d426b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/2.0.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.4.0 requests-toolbelt/0.9.1 tqdm/4.36.1 CPython/3.6.7

Security for pooch 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.6.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page