Metadata-Version: 2.1
Name: cldfcatalog
Version: 1.7.0
Summary: A Python library to access CLDF reference catalogs
Home-page: https://github.com/cldf/cldfcatalog
Author: Robert Forkel
Author-email: robert_forkel@eva.mpg.de
License: Apache 2.0
Project-URL: Bug Tracker, https://github.com/cldf/cldfcatalog/issues
Keywords: linguistics
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pycldf>=1.24
Requires-Dist: gitpython
Requires-Dist: platformdirs
Provides-Extra: dev
Requires-Dist: tox; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: wheel>=0.36; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=5; extra == "test"
Requires-Dist: pytest-mock; extra == "test"
Requires-Dist: pytest-cov; extra == "test"

# cldfcatalog

Utilities to use `git` repository clones and reference catalogs.

[![Build Status](https://github.com/cldf/cldfcatalog/workflows/tests/badge.svg)](https://github.com/cldf/cldfcatalog/actions?query=workflow%3Atests)
[![PyPI](https://img.shields.io/pypi/v/cldfcatalog.svg)](https://pypi.org/project/cldfcatalog)

Research data - and in particular CLDF data - is often curated using `git` repositories
for version control. [`cldfcatalog.Repository`](src/cldfcatalog/repository.py) 
provides a wrapper around GitPython's `git.Repo` class, exposing relevant functionality 
in this context.

A particularly important piece of data for CLDF are reference catalogs, which are
consulted during CLDF data creation. Again, such catalogs are often available as
`git` repositories hosted on GitHub, such as 
[Glottolog](https://github.com/glottolog/glottolog) or
[Concepticon](https://github.com/concepticon/concepticon-data).

The typical usage scenario for these catalogs is as follows: 
- To follow upstream development of the catalogs, a user has a local clone of the
  repository, which is periodically synched running `git pull origin`.
- When creating a CLDF dataset, a particular released version of a catalog is consulted.

Thus, we want to 
- checkout a particular version of the catalog,
- run the CLDF creation,
- restore the previous state of the repository clone.

This is exactly the functionality of [`cldfcatalog.Catalog`](src/cldfcatalog/catalog.py):
```python
>>> from cldfcatalog import Catalog
>>> glottolog = Catalog('../../glottolog/glottolog', 'v4.0')
>>> glottolog.active_branch
'master'
>>> with glottolog:
...     print(glottolog.describe())
...     
v4.0
>>> glottolog.describe()
'v4.0-52-ga4cfc90'
```


## Configuration

`cldfcatalog` supports discovery of local paths to catalog clones via a configuration file.
If a file `catalog.ini` is found at `platformdirs.user_config_dir('cldf')` (see [platformdirs](https://pypi.org/project/platformdirs/)) is found, its `clones` section is used as a
mapping from `Catalog.cli_name()` to clone path. Thus, with a configuration
```ini
[clones]
clts = /home/forkel/.config/cldf/clts
```
a catalog can be intialized as
```python
with Catalog.from_config('clts', tag='v1.0'):
    ...
```

When cloning a catalog,
running `Catalog.clone`,`appdirs.user_config_dir('cldf')` will be used as directory for
the clone, and the path will be written to the config file.

To add add paths to a config file use it as context manager:
```python
from cldfcatalog import Config

with Config.from_file() as cfg:
    cfg.add_clone(key, path)
```
