Helper module to easily develop special remotes for git annex. AnnexRemote handles all the protocol stuff for you, so you can focus on the remote itself. It implements the complete 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.
You need python installed on your system. AnnexRemote has been tested with version 2.7 and 3.4 to 3.7.
pip install annexremote
Running the tests
If you want to run the tests, copy the content of the
tests folder to the same location as
Then use a test discovery like nose to run them.
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
main function, link your remote to the master class and initialize the protocol:
def main(): master = Master() 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
That's it. Now you've created your special remote.
Import and subtype
ExportRemote instead of
# ... from annexremote import ExportRemote class MyRemote(ExportRemote): # implement the remote methods just like in the above example and then additionally: def transferexport_store(self, key, local_file, remote_file): # store the file located at `local_file` to `remote_file` on the remote # raise RemoteError if the file couldn't be stored def transferexport_retrieve(self, key, local_file, remote_file): # get the file located at `remote_file` from the remote and store it to `local_file` # raise RemoteError if the file couldn't be retrieved def checkpresentexport(self, key, remote_file): # return True if the file `remote_file` is present in the remote # return False if not # raise RemoteError if the presence of the file couldn't be determined, eg. in case of connection error def removeexport(self, key, remote_file): # remove the file in `remote_file` from the remote # raise RemoteError if it couldn't be removed # note that removing a not existing key isn't considered an error def removeexportdirectory(self, remote_directory): # remove the directory `remote_directory` from the remote # raise RemoteError if it couldn't be removed # note that removing a not existing directory isn't considered an error def renameexport(self, key, filename, new_filename): # move the remote file in `name` to `new_name` # raise RemoteError if it couldn't be moved
A full documentation is being worked on. Until then, have a look at the example and check the test cases in order to see how the other methods are used. Also have a look at git-annex-remote-googledrive which is based on AnnexRemote.
This project is licensed under GPLv3 - see the LICENSE file for details