Metadata-Version: 2.1
Name: git-annex-adapter
Version: 0.2.2
Summary: Call git-annex commands from Python
Home-page: https://github.com/alpernebbi/git-annex-adapter
Author: Alper Nebi Yasak
Author-email: alpernebiyasak@gmail.com
License: GPL3+
Keywords: git-annex metadata
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Requires-Dist: pygit2

=================
Git-Annex-Adapter
=================
This package lets you interact with git-annex_ from within Python.
Necessary commands are executed using ``subprocess`` and use their
batch versions whenever possible.

.. _git-annex: https://git-annex.branchable.com/

I'm developing this as needed, so feel free to ask if there's any
functionality you want me to implement.

Requirements
------------
- Python 3
- git-annex 6.20170101 (or later)
- pygit2 0.24 (or later)

Usage
-----
To create a git-annex repository from scratch::

    >>> from pygit2 import init_repository
    >>> from git_annex_adapter import init_annex

    >>> init_repository('/path/to/repo')
    pygit2.Repository('/path/to/repo/.git/')

    >>> init_annex('/path/to/repo')
    git_annex_adapter.repo.GitAnnexRepo(/path/to/repo/.git/)

To wrap an existing git-annex repository::

    >>> from git_annex_adapter.repo import GitAnnexRepo
    >>> repo = GitAnnexRepo('/tmp/repo')

The GitAnnexRepo is a subclass of pygit2.Repository. Git-annex specific
functionality is accessed via the ``annex`` property of it, which is
a mapping object from git-annex keys to ``AnnexedFile`` objects::

    >>> for key in repo.annex:
    ...     print(key)
    SHA256E-s3--2c26...
    SHA256E-s3--baa5...
    SHA256E-s3--fcde...

    >>> key = 'SHA256E-s3--2c26...'
    >>> repo.annex[key]
    git_annex_adapter.repo.AnnexedFile('SHA256E-s3--2c26...')

You can also get a tree representation of any git tree-ish object with
annexed file entries replaced with ``AnnexedFile`` objects::

    >>> tree = repo.annex.get_file_tree() # treeish='HEAD'
    >>> tree
    git_annex_adapter.repo.AnnexedFileTree(4d7f...)

    >>> set(tree)
    {'foo', 'bar', 'baz', 'README', 'directory'}

    >>> tree['foo']
    git_annex_adapter.repo.AnnexedFile(SHA256E-s3--2c26...)

    >>> tree['directory']
    git_annex_adapter.repo.AnnexedFileTree(8b54...)

    >>> tree['directory/file'] # or tree['directory']['file']
    <pygit2.Blob object at 0x...>

The ``AnnexedFile`` objects can be used to access and manipulate
information about a file.

The ``metadata`` property of the ``AnnexedFile`` is a mutable mapping
object from fields to sets of values::

    >>> foo = tree['foo']
    >>> for field, values in foo.metadata:
    ...     print('{}: {}'.format(field, values))
    author: {'me'}
    numbers: {'1', '2', '3'}

    >>> foo.metadata['numbers'] |= {'0'}
    >>> foo.metadata['numbers'] -= {'3'}
    >>> foo.metadata['numbers']
    {'0', '2'}

    >>> del foo.metadata['author']
    >>> 'author' in foo.metadata
    False

    >>> foo.metadata['lastchanged']
    '2017-07-19@15-00-00'

Calling Processes
-----------------

If you need low-level access to the git-annex processes, you can do it
via the classes included in ``process`` module::

    >>> from git_annex_adapter.process import ...

Subclasses of ``GitAnnexBatchProcess`` return relevant output (usually
one line or a dict object) whenever called with a line of input.
For example, ``git-annex metadata --batch --json``::

    >>> proc = GitAnnexMetadataBatchJsonProcess('/path/to/repo')
    >>> proc(file='foo')
    {..., 'key':'SHA256E-s3--2c26...', 'fields': ...}

    >>> proc(file='foo', fields={'numbers': ['1', '2', '3']})
    {..., 'key': ..., 'fields': {'numbers': ['1', '2', '3'], ...}}

Subclasses of ``GitAnnexRunner`` call a single program with
different arguments. They return a ``subprocess.CompletedProcess``
when called, which captures stdout and stderr. For example, to run
``git-annex version``::

    >>> runner = GitAnnexVersionRunner('/path/to/repo')
    >>> runner(raw=True)
    CompletedProcess(..., stdout='6.20170101', stderr='')

    >>> print(runner().stdout)
    git-annex version: 6.20170101
    ...



