Fix #95 Add id2filename Docs (#108)

This adds some docs for `id2filename` and a reverse method that
turns a valid path into and `ID`.

Signed-off-by: David Brown <dmlb2000@gmail.com>

docs/configuration.md

@@ -60,6 +60,7 @@ into bytes. Each byte is then represented in hex and used to build the directory
 tree.
 
 For example `id2filename(12345)` becomes `/39/3039` on the backend file system.
+See more documentation in the [id2filename module](archivei.id2filename).
 
 ## Running It
 

pacifica/archiveinterface/id2filename.py

@@ -1,11 +1,29 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
-"""Module to Convert an integer id to a filepath for storage system."""
+"""
+Module to convert an integer id to a filepath for storage system.
+
+Mathematically, this is a bijective_ set of methods. This means that
+running `filename2id(id2filename(ID))` must return the same `ID`
+passed and conversely `id2filename(filename2id(PATH))` must return
+the same `PATH` passed.
+
+Example usage:
+
+::
+
+  >>> id2filename(1234)
+  '/d2/4d2'
+  >>> filename2id('/d2/4d2')
+  1234
+
+.. _bijective: https://en.wikipedia.org/wiki/Bijection
+"""
 from __future__ import print_function
 import sys
 
 
-def id2dirandfilename(fileid):
+def id2filename(fileid):
     """Algorithm for getting filepath from an integer id."""
     hexfileid = '{0:x}'.format(fileid)
     directories = ''
@@ -22,9 +40,11 @@ def id2dirandfilename(fileid):
     return filepath
 
 
-def id2filename(fileid):
-    """Will return the filepath associated to passed fileid."""
-    return id2dirandfilename(fileid)
+def filename2id(path):
+    """Convert a filepath to and ID."""
+    if path[:6] == '/file.':
+        return int(path[6:], 16)
+    return int(path.split('/')[-1], 16)
 
 
 if __name__ == '__main__':  # pragma: no cover

tests/interface_test.py

@@ -5,7 +5,7 @@
 import unittest
 import time
 from pacifica.archiveinterface.archive_utils import un_abs_path, get_http_modified_time
-from pacifica.archiveinterface.id2filename import id2filename
+from pacifica.archiveinterface.id2filename import id2filename, filename2id
 from pacifica.archiveinterface.exception import ArchiveInterfaceError
 from pacifica.archiveinterface.rest_generator import ArchiveInterfaceGenerator
 from pacifica.archiveinterface.backends.factory import ArchiveBackendFactory
@@ -89,6 +89,21 @@ def test_id2filename_o_shift_point(self):
         filename = id2filename((32 * 1024) + 1)
         self.assertEqual(filename, '/01/8001')
 
+    def test_filename2id_all(self):
+        """Test all the filenames to ids and vice versa."""
+        filemap = {
+            '/01/8001': (32*1024)+1,
+            '/00/8000': (32*1024),
+            '/ff/7fff': (32*1024)-1,
+            '/file.1': 1,
+            '/file.0': 0,
+            '/file.-1': -1,
+            '/d2/4d2': 1234
+        }
+        for filename, fileid in filemap.items():
+            self.assertEqual(fileid, filename2id(filename), '{} should equal {}'.format(fileid, filename2id(filename)))
+            self.assertEqual(id2filename(fileid), filename, '{} should equal {}'.format(id2filename(fileid), filename))
+
 
 class TestBackendArchive(unittest.TestCase, SetupTearDown):
     """Test the backend archive."""