Skip to main content
Help us improve PyPI by participating in user testing. All experience levels needed!

git annex special remotes made easy

Project description

# AnnexRemote
Helper module to easily develop special remotes for [git annex](https://git-annex.branchable.com).
AnnexRemote handles all the protocol stuff for you, so you can focus on the remote itself.
It implements the complete [external special remote protocol](https://git-annex.branchable.com/design/external_special_remote_protocol)
and fulfils all specifications regarding whitespaces etc. This is ensured by an excessive test suite.
Extensions to the protocol are normally added within hours after they've been published.

## Getting started
### Prerequisites
You need python3 installed on your system. AnnexRemote has been tested with version 3.4 to 3.6.

### Installing
`pip3 install annexremote`

### Running the tests
If you want to run the tests, copy the content of the `tests` folder to the same location as `annexremote.py`.
Then use a test discovery like [nose](http://nose.readthedocs.io) to run them.

### Usage

Import the necessary classes

```
from annexremote import Master
from annexremote import SpecialRemote
from annexremote import RemoteError
```

Now create your special remote class. It must subtype ``SpecialRemote`` and implement at least the 6 basic methods:

```
class MyRemote(SpecialRemote):
def initremote(self):
# initialize the remote, eg. create the folders
# raise RemoteError if the remote couldn't be initialized

def prepare(self):
# prepare to be used, eg. open TCP connection, authenticate with the server etc.
# raise RemoteError if not ready to use

def transfer_store(self, key, filename):
# store the file in `filename` to a unique location derived from `key`
# raise RemoteError if the file couldn't be stored

def transfer_retrieve(self, key, filename):
# get the file identified by `key` and store it to `filename`
# raise RemoteError if the file couldn't be retrieved

def checkpresent(self, key):
# return True if the key is present in the remote
# return False if the key is not present
# raise RemoteError if the presence of the key couldn't be determined, eg. in case of connection error

def remove(self, key):
# remove the key from the remote
# raise RemoteError if it couldn't be removed
# note that removing a not existing key isn't considered an error
```

In your ``main`` function, link your remote to the master class and initialize the protocol:

```
def main():
master = RemoteMaster()
remote = MyRemote(master)
master.LinkRemote(remote)
master.Listen()

if __name__ == "__main__":
main()
```

Now save your program as ``git-annex-remote-$something`` and make it executable.

``chmod +x git-annex-remote-$something``
(You'll need the sheebang line ``#!/usr/bin/env python3``)

That's it. Now you've created your special remote.

### Using other requests
A full documentation is being worked on. Until then, check the test cases in order to see how the other methods are used. Also have a look at [git-annex-remote-googledrive](https://github.com/Lykos153/git-annex-remote-googledrive) which is based on AnnexRemote.

## License

This project is licensed under GPLv3 - see the [LICENSE](LICENSE) file for details



Project details


Release history Release notifications

This version
History Node

1.1.1

History Node

1.1.post1

History Node

1.1.0

History Node

1.0.1

History Node

1.0.post2

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
annexremote-1.1.1-py3-none-any.whl (9.4 kB) Copy SHA256 hash SHA256 Wheel py3 Mar 28, 2018
annexremote-1.1.1.tar.gz (24.1 kB) Copy SHA256 hash SHA256 Source None Mar 28, 2018

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page