{"author":null,"author_email":"The Pooch Developers ","bugtrack_url":null,"classifiers":["Development Status :: 5 - Production/Stable","Intended Audience :: Developers","Intended Audience :: Education","Intended Audience :: Science/Research","License :: OSI Approved :: BSD License","Operating System :: OS Independent","Programming Language :: Python :: 3 :: Only","Programming Language :: Python :: 3.10","Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.7","Programming Language :: Python :: 3.8","Programming Language :: Python :: 3.9","Topic :: Scientific/Engineering","Topic :: Software Development :: Libraries"],"description":" $\"Pooch:$ \n\n

\nDocumentation (latest) •\nDocumentation (main branch) •\nContributing •\nContact\n

\n\n

\nPart of the Fatiando a Terra project\n

\n\n

\n $\"Latest$ \n $\"Latest$ \n $\"Test$ \n $\"Compatible$ \n $\"DOI$ \n

\n\n## About\n\n> Just want to download a file without messing with `requests` and `urllib`?\n> Trying to add sample datasets to your Python package?\n> **Pooch is here to help!**\n\n*Pooch* is a **Python library** that can manage data by **downloading files**\nfrom a server (only when needed) and storing them locally in a data **cache**\n(a folder on your computer).\n\n* Pure Python and minimal dependencies.\n* Download files over HTTP, FTP, and from data repositories like Zenodo and figshare.\n* Built-in post-processors to unzip/decompress the data after download.\n* Designed to be extended: create custom downloaders and post-processors.\n\nAre you a **scientist** or researcher? Pooch can help you too!\n\n* Host your data on a repository and download using the DOI.\n* Automatically download data using code instead of telling colleagues to do it themselves.\n* Make sure everyone running the code has the same version of the data files.\n\n## Projects using Pooch\n\n[SciPy](https://github.com/scipy/scipy), \n[scikit-image](https://github.com/scikit-image/scikit-image),\n[xarray](https://github.com/pydata/xarray),\n[Ensaio](https://github.com/fatiando/ensaio),\n[GemPy](https://github.com/cgre-aachen/gempy),\n[MetPy](https://github.com/Unidata/MetPy),\n[napari](https://github.com/napari/napari),\n[Satpy](https://github.com/pytroll/satpy),\n[yt](https://github.com/yt-project/yt),\n[PyVista](https://github.com/pyvista/pyvista),\n[icepack](https://github.com/icepack/icepack),\n[histolab](https://github.com/histolab/histolab),\n[seaborn-image](https://github.com/SarthakJariwala/seaborn-image),\n[Open AR-Sandbox](https://github.com/cgre-aachen/open_AR_Sandbox),\n[climlab](https://github.com/climlab/climlab),\n[mne-python](https://github.com/mne-tools/mne-python),\n[GemGIS](https://github.com/cgre-aachen/gemgis),\n[SHTOOLS](https://github.com/SHTOOLS/SHTOOLS),\n[MOABB](https://github.com/NeuroTechX/moabb),\n[GeoViews](https://github.com/holoviz/geoviews),\n[ScopeSim](https://github.com/AstarVienna/ScopeSim),\n[Brainrender](https://github.com/brainglobe/brainrender),\n[pyxem](https://github.com/pyxem/pyxem),\n[cellfinder](https://github.com/brainglobe/cellfinder),\n[PVGeo](https://github.com/OpenGeoVis/PVGeo),\n[geosnap](https://github.com/oturns/geosnap),\n[BioCypher](https://github.com/biocypher/biocypher),\n[cf-xarray](https://github.com/xarray-contrib/cf-xarray),\n[Scirpy](https://github.com/scverse/scirpy),\n[rembg](https://github.com/danielgatis/rembg),\n[DASCore](https://github.com/DASDAE/dascore),\n[scikit-mobility](https://github.com/scikit-mobility/scikit-mobility),\n[Py-ART](https://github.com/ARM-DOE/pyart),\n[HyperSpy](https://github.com/hyperspy/hyperspy),\n[RosettaSciIO](https://github.com/hyperspy/rosettasciio),\n[eXSpy](https://github.com/hyperspy/exspy)\n\n\n> If you're using Pooch, **send us a pull request** adding your project to the list.\n\n## Example\n\nFor a **scientist downloading a data file** for analysis:\n\n```python\nimport pooch\nimport pandas as pd\n\n# Download a file and save it locally, returning the path to it.\n# Running this again will not cause a download. Pooch will check the hash\n# (checksum) of the downloaded file against the given value to make sure\n# it's the right file (not corrupted or outdated).\nfname_bathymetry = pooch.retrieve(\n url=\"https://github.com/fatiando-data/caribbean-bathymetry/releases/download/v1/caribbean-bathymetry.csv.xz\",\n known_hash=\"md5:a7332aa6e69c77d49d7fb54b764caa82\",\n)\n\n# Pooch can also download based on a DOI from certain providers.\nfname_gravity = pooch.retrieve(\n url=\"doi:10.5281/zenodo.5882430/southern-africa-gravity.csv.xz\",\n known_hash=\"md5:1dee324a14e647855366d6eb01a1ef35\",\n)\n\n# Load the data with Pandas\ndata_bathymetry = pd.read_csv(fname_bathymetry)\ndata_gravity = pd.read_csv(fname_gravity)\n```\n\nFor **package developers** including sample data in their projects:\n\n```python\n\"\"\"\nModule mypackage/datasets.py\n\"\"\"\nimport pkg_resources\nimport pandas\nimport pooch\n\n# Get the version string from your project. You have one of these, right?\nfrom . import version\n\n# Create a new friend to manage your sample data storage\nGOODBOY = pooch.create(\n # Folder where the data will be stored. For a sensible default, use the\n # default cache folder for your OS.\n path=pooch.os_cache(\"mypackage\"),\n # Base URL of the remote data store. Will call .format on this string\n # to insert the version (see below).\n base_url=\"https://github.com/myproject/mypackage/raw/{version}/data/\",\n # Pooches are versioned so that you can use multiple versions of a\n # package simultaneously. Use PEP440 compliant version number. The\n # version will be appended to the path.\n version=version,\n # If a version as a \"+XX.XXXXX\" suffix, we'll assume that this is a dev\n # version and replace the version with this string.\n version_dev=\"main\",\n # An environment variable that overwrites the path.\n env=\"MYPACKAGE_DATA_DIR\",\n # The cache file registry. A dictionary with all files managed by this\n # pooch. Keys are the file names (relative to *base_url*) and values\n # are their respective SHA256 hashes. Files will be downloaded\n # automatically when needed (see fetch_gravity_data).\n registry={\"gravity-data.csv\": \"89y10phsdwhs09whljwc09whcowsdhcwodcydw\"}\n)\n# You can also load the registry from a file. Each line contains a file\n# name and it's sha256 hash separated by a space. This makes it easier to\n# manage large numbers of data files. The registry file should be packaged\n# and distributed with your software.\nGOODBOY.load_registry(\n pkg_resources.resource_stream(\"mypackage\", \"registry.txt\")\n)\n\n# Define functions that your users can call to get back the data in memory\ndef fetch_gravity_data():\n \"\"\"\n Load some sample gravity data to use in your docs.\n \"\"\"\n # Fetch the path to a file in the local storage. If it's not there,\n # we'll download it.\n fname = GOODBOY.fetch(\"gravity-data.csv\")\n # Load it with numpy/pandas/etc\n data = pandas.read_csv(fname)\n return data\n```\n\n## Getting involved\n\n🗨️ **Contact us:**\nFind out more about how to reach us at\n[fatiando.org/contact](https://www.fatiando.org/contact/).\n\n👩🏾‍💻 **Contributing to project development:**\nPlease read our\n[Contributing Guide](https://github.com/fatiando/pooch/blob/main/CONTRIBUTING.md)\nto see how you can help and give feedback.\n\n🧑🏾‍🤝‍🧑🏼 **Code of conduct:**\nThis project is released with a\n[Code of Conduct](https://github.com/fatiando/community/blob/main/CODE_OF_CONDUCT.md).\nBy participating in this project you agree to abide by its terms.\n\n> **Imposter syndrome disclaimer:**\n> We want your help. **No, really.** There may be a little voice inside your\n> head that is telling you that you're not ready, that you aren't skilled\n> enough to contribute. We assure you that the little voice in your head is\n> wrong. Most importantly, **there are many valuable ways to contribute besides\n> writing code**.\n>\n> *This disclaimer was adapted from the*\n> [MetPy project](https://github.com/Unidata/MetPy).\n\n## License\n\nThis is free software: you can redistribute it and/or modify it under the terms\nof the **BSD 3-clause License**. A copy of this license is provided in\n[`LICENSE.txt`](https://github.com/fatiando/pooch/blob/main/LICENSE.txt).\n","description_content_type":"text/markdown","docs_url":null,"download_url":null,"downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":null,"home_page":null,"keywords":"data, download, caching, http","license":"BSD-3-Clause","license_expression":null,"license_files":null,"maintainer":null,"maintainer_email":"Leonardo Uieda ","name":"pooch","package_url":"https://pypi.org/project/pooch/","platform":null,"project_url":"https://pypi.org/project/pooch/","project_urls":{"Bug Tracker":"https://github.com/fatiando/pooch/issues","Changelog":"https://www.fatiando.org/pooch/latest/changes.html","Documentation":"https://www.fatiando.org/pooch","Source Code":"https://github.com/fatiando/pooch"},"provides_extra":null,"release_url":"https://pypi.org/project/pooch/1.8.2/","requires_dist":["platformdirs>=2.5.0","packaging>=20.0","requests>=2.19.0","tqdm<5.0.0,>=4.41.0; extra == \"progress\"","paramiko>=2.7.0; extra == \"sftp\"","xxhash>=1.4.3; extra == \"xxhash\""],"requires_python":">=3.7","summary":"A friend to fetch your data files","version":"1.8.2","yanked":false,"yanked_reason":null}

Dependency	Optional
packaging	false
platformdirs	false
requests	false
paramiko	true
tqdm	true
xxhash	true

Package search

pooch

project_urls

Dependencies

All package metadata

Releases