Merge pull request #258 from jacebrowning/home-paths

Add support for paths relative to home directories

CHANGELOG.md

@@ -1,3 +1,7 @@
+# 1.3 (alpha)
+
+- Added support for paths relative to the user's home directory.
+
 # 1.2 (2022-02-24)
 
 - Added a `frozen()` context manager to temporarily disable file updates.

Makefile

@@ -96,6 +96,7 @@ $(MKDOCS_INDEX): docs/requirements.txt mkdocs.yml docs/*.md
 
 docs/requirements.txt: poetry.lock
 	@ rm -f $@
+	@ poetry export --dev --without-hashes | grep jinja2 >> $@
 	@ poetry export --dev --without-hashes | grep markdown >> $@
 	@ poetry export --dev --without-hashes | grep mkdocs >> $@
 	@ poetry export --dev --without-hashes | grep pygments >> $@

datafiles/mapper.py

@@ -54,6 +54,8 @@ def path(self) -> Optional[Path]:
         path = Path(self._pattern.format(self=self._instance))
         if path.is_absolute() or self._pattern.startswith("./"):
             return path.resolve()
+        if self._pattern.startswith("~/"):
+            return path.expanduser()
 
         cls = self._instance.__class__
         try:

datafiles/tests/test_mapper.py

@@ -58,6 +58,11 @@ def is_relative_to_cwd_when_specified(expect, mapper):
                 path = Path.cwd() / "foobar" / "sample.yml"
             expect(mapper.path) == path
 
+        def is_relative_to_home_when_specified(expect, mapper):
+            mapper._pattern = "~/foobar/sample.yml"
+            path = Path.home() / "foobar" / "sample.yml"
+            expect(mapper.path) == path
+
     def describe_relpath():
         def when_cwd_is_parent(expect, mapper):
             mapper._pattern = "../../tmp/sample.yml"

docs/api/model.md

@@ -57,6 +57,7 @@ Filename patterns are relative to the file in which the model is defined unless
 - Absolute: `/tmp/items/{self.name}.yml`
 - Relative to model: `items/{self.name}.yml`
 - Relative to current directory: `./items/{self.name}.yml`
+- Relative to the user's home directory: `~/items/{self.name}.yml`
 
 Attributes included in the filename pattern and those with default value are automatically excluded from serialization since these redundant values are not required to restore objects from disk.
 

docs/requirements.txt

@@ -1,3 +1,4 @@
+jinja2==3.0.3; python_version >= "3.6"
 markdown==3.3.4; python_version >= "3.6"
 mkdocs==1.2.3; python_version >= "3.6"
 jupyterlab-pygments==0.1.2; python_version >= "3.6"

pyproject.toml

@@ -1,7 +1,7 @@
 [tool.poetry]
 
 name = "datafiles"
-version = "1.2"
+version = "1.3a1"
 description = "File-based ORM for dataclasses."
 
 license = "MIT"
@@ -86,6 +86,7 @@ coveragespace = "^4.0"
 # Documentation
 mkdocs = "^1.2.3"
 pygments = "^2.10"
+jinja2 = "~3.0.3" # fix for 'mkdocs' incompatiblity
 
 # Notebooks
 idna = "^3.3" # papermill dependency