Make synced collection a hidden package

changelog.txt

@@ -56,6 +56,7 @@ Removed
  - The ability to call ``Project.workspace``, it is strictly a property now (#752).
  - ``ProjectSchema.__call__``, ``ProjectSchema.detect`` (#752).
  - The ``--doc-filter`` option for several command line subcommands (#613, #795).
+ - The public API of the ``synced_collection`` subpackage (#807, #790).
 
 Version 1
 =========

doc/api.rst

@@ -173,111 +173,3 @@ signac.errors module
     :members:
     :undoc-members:
     :show-inheritance:
-
-synced\_collections package
-===========================
-
-Data Types
-----------
-
-synced\_collections.synced\_collection module
-+++++++++++++++++++++++++++++++++++++++++++++
-
-.. automodule:: signac.synced_collections.data_types.synced_collection
-   :members:
-   :private-members:
-   :show-inheritance:
-
-synced\_collections.synced\_dict module
-+++++++++++++++++++++++++++++++++++++++
-
-.. automodule:: signac.synced_collections.data_types.synced_dict
-   :members:
-   :show-inheritance:
-
-synced\_collections.synced\_list module
-+++++++++++++++++++++++++++++++++++++++
-
-.. automodule:: signac.synced_collections.data_types.synced_list
-   :members:
-   :show-inheritance:
-
-Backends
---------
-
-synced\_collections.backends.collection\_json module
-++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-.. automodule:: signac.synced_collections.backends.collection_json
-   :members:
-   :show-inheritance:
-
-synced\_collections.backends.collection\_mongodb module
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-.. automodule:: signac.synced_collections.backends.collection_mongodb
-   :members:
-   :show-inheritance:
-
-synced\_collections.backends.collection\_redis module
-+++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-.. automodule:: signac.synced_collections.backends.collection_redis
-   :members:
-   :show-inheritance:
-
-synced\_collections.backends.collection\_zarr module
-++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-.. automodule:: signac.synced_collections.backends.collection_zarr
-   :members:
-   :show-inheritance:
-
-Buffers
--------
-
-synced\_collections.buffers.buffered\_collection module
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-.. automodule:: signac.synced_collections.buffers.buffered_collection
-   :members:
-   :private-members:
-   :show-inheritance:
-
-synced\_collections.buffers.file\_buffered\_collection module
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-.. automodule:: signac.synced_collections.buffers.file_buffered_collection
-   :members:
-   :show-inheritance:
-
-synced\_collections.buffers.serialized\_file\_buffered\_collection module
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-.. automodule:: signac.synced_collections.buffers.serialized_file_buffered_collection
-   :members:
-   :show-inheritance:
-
-synced\_collections.buffers.memory\_buffered\_collection module
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-.. automodule:: signac.synced_collections.buffers.memory_buffered_collection
-   :members:
-   :show-inheritance:
-
-Miscellaneous Modules
----------------------
-
-synced\_collections.utils module
-++++++++++++++++++++++++++++++++
-
-.. automodule:: signac.synced_collections.utils
-   :members:
-   :show-inheritance:
-
-synced\_collections.validators module
-+++++++++++++++++++++++++++++++++++++
-
-.. automodule:: signac.synced_collections.validators
-   :members:
-   :show-inheritance:

signac/__init__.py

@@ -10,12 +10,12 @@
 """
 
 from . import contrib, errors, sync, testing, warnings
+from ._synced_collections.backends.collection_json import (
+    BufferedJSONAttrDict as JSONDict,
+)
 from .contrib import Project, TemporaryProject, get_job, get_project, init_project
 from .core.h5store import H5Store, H5StoreManager
 from .diff import diff_jobs
-from .synced_collections.backends.collection_json import (
-    BufferedJSONAttrDict as JSONDict,
-)
 from .version import __version__
 
 # Alias some properties related to buffering into the signac namespace.

signac/synced_collections/buffers/buffered_collection.py → signac/_synced_collections/buffers/buffered_collection.py

@@ -67,7 +67,7 @@ class BufferedCollection(SyncedCollection):
 
         - :meth:`~._load_from_buffer`: Loads data while in buffered mode and returns
           it in an object satisfying
-          :meth:`~signac.synced_collections.data_types.synced_collection.SyncedCollection.is_base_type`.
+          :meth:`~signac._synced_collections.data_types.synced_collection.SyncedCollection.is_base_type`.
           The default behavior is to simply call
           :meth:`~._load_from_resource`.
         - :meth:`~._save_to_buffer`: Stores data while in buffered mode. The default behavior
@@ -159,7 +159,7 @@ def _load_from_buffer(self):
         -------
         Collection
             An equivalent unsynced collection satisfying
-            :meth:`~signac.synced_collections.data_types.synced_collection.SyncedCollection.is_base_type` that
+            :meth:`~signac._synced_collections.data_types.synced_collection.SyncedCollection.is_base_type` that
             contains the buffered data. By default, the buffered data is just the
             data in the resource.
 

signac/contrib/hashing.py

@@ -6,7 +6,7 @@
 import hashlib
 import json
 
-from ..synced_collections.utils import SyncedCollectionJSONEncoder
+from .._synced_collections.utils import SyncedCollectionJSONEncoder
 
 # We must use the standard library json for exact consistency in formatting
 

signac/contrib/job.py

@@ -12,14 +12,14 @@
 from threading import RLock
 from typing import FrozenSet
 
-from ..core.h5store import H5StoreManager
-from ..sync import sync_jobs
-from ..synced_collections.backends.collection_json import (
+from .._synced_collections.backends.collection_json import (
     BufferedJSONAttrDict,
     JSONAttrDict,
     json_attr_dict_validator,
 )
-from ..synced_collections.errors import KeyTypeError
+from .._synced_collections.errors import KeyTypeError
+from ..core.h5store import H5StoreManager
+from ..sync import sync_jobs
 from .errors import DestinationExistsError, JobsCorruptedError
 from .hashing import calc_id
 from .utility import _mkdir_p
@@ -403,7 +403,7 @@ def statepoint(self):
             you can access a dict copy of the state point by calling it, e.g.
             ``sp_dict = job.statepoint()`` instead of ``sp = job.statepoint``.
             For more information, see
-            :class:`~signac.synced_collections.backends.collection_json.JSONAttrDict`.
+            :class:`~signac._synced_collections.backends.collection_json.JSONAttrDict`.
 
         See :ref:`signac statepoint <signac-cli-statepoint>` for the command line equivalent.
 
@@ -415,8 +415,9 @@ def statepoint(self):
 
         Returns
         -------
-        dict
-            Returns the job's state point.
+        MutableMapping
+            Returns the job's state point. Supports attribute-based access to
+            dict keys.
         """
         with self._lock:
             if self._statepoint_requires_init:
@@ -481,8 +482,8 @@ def document(self):
 
         Returns
         -------
-        :class:`~signac.JSONDict`
-            The job document handle.
+        MutableMapping
+            The job document handle. Supports attribute-based access to dict keys.
 
         """
         with self._lock:
@@ -522,8 +523,8 @@ def doc(self):
 
         Returns
         -------
-        :class:`~signac.JSONDict`
-            The job document handle.
+        MutableMapping
+            The job document handle. Supports attribute-based access to dict keys.
 
         """
         return self.document

signac/contrib/migration/v1_to_v2.py

@@ -15,10 +15,10 @@
 
 import os
 
+from signac._synced_collections.backends.collection_json import BufferedJSONAttrDict
 from signac.common import configobj
 from signac.common.config import _get_project_config_fn
 from signac.contrib.project import Project
-from signac.synced_collections.backends.collection_json import BufferedJSONAttrDict
 
 from .v0_to_v1 import _load_config_v1
 

signac/contrib/project.py

@@ -19,6 +19,7 @@
 from tempfile import TemporaryDirectory
 from threading import RLock
 
+from .._synced_collections.backends.collection_json import BufferedJSONAttrDict
 from ..common.config import (
     Config,
     _get_project_config_fn,
@@ -28,7 +29,6 @@
 )
 from ..core.h5store import H5StoreManager
 from ..sync import sync_projects
-from ..synced_collections.backends.collection_json import BufferedJSONAttrDict
 from ..version import SCHEMA_VERSION, __version__
 from ._searchindexer import _SearchIndexer
 from .errors import (
@@ -301,8 +301,8 @@ def document(self):
 
         Returns
         -------
-        :class:`~signac.synced_collections.backends.collection_json.BufferedJSONAttrDict`
-            The project document.
+        MutableMapping
+            The project document. Supports attribute-based access to dict keys.
 
         """
         with self._lock:
@@ -334,8 +334,8 @@ def doc(self):
 
         Returns
         -------
-        :class:`~signac.synced_collections.backends.collection_json.BufferedJSONAttrDict`
-            The project document.
+        MutableMapping
+            The project document. Supports attribute-based access to dict keys.
 
         """
         return self.document

signac/errors.py

@@ -7,6 +7,7 @@
 # exceptions that are relevant beyond a single module. This top-level errors
 # module is used to expose user-facing exception classes.
 
+from ._synced_collections.errors import InvalidKeyError, KeyTypeError
 from .common.errors import ConfigError
 from .contrib.errors import (
     DestinationExistsError,
@@ -16,7 +17,6 @@
     WorkspaceError,
 )
 from .core.errors import Error, H5StoreAlreadyOpenError, H5StoreClosedError
-from .synced_collections.errors import InvalidKeyError, KeyTypeError
 
 
 class SyncConflict(Error, RuntimeError):

tests/test_buffered_mode.py

@@ -12,7 +12,7 @@
 from test_project import TestProjectBase
 
 import signac
-from signac.synced_collections.errors import BufferedError
+from signac._synced_collections.errors import BufferedError
 
 PYPY = "PyPy" in platform.python_implementation()
 

tests/test_numpy_integration.py

@@ -4,7 +4,7 @@
 import pytest
 from test_project import TestProjectBase
 
-from signac.synced_collections.numpy_utils import NumpyConversionWarning
+from signac._synced_collections.numpy_utils import NumpyConversionWarning
 
 try:
     import numpy  # noqa

tests/test_synced_collections/synced_collection_test.py

@@ -8,9 +8,9 @@
 
 import pytest
 
+from signac._synced_collections import SyncedCollection
+from signac._synced_collections.numpy_utils import NumpyConversionWarning
 from signac.errors import KeyTypeError
-from signac.synced_collections import SyncedCollection
-from signac.synced_collections.numpy_utils import NumpyConversionWarning
 
 PYPY = "PyPy" in platform.python_implementation()
 

tests/test_synced_collections/test_json_buffered_collection.py

@@ -11,7 +11,7 @@
 from attr_dict_test import AttrDictTest, AttrListTest
 from test_json_collection import JSONCollectionTest, TestJSONDict, TestJSONList
 
-from signac.synced_collections.backends.collection_json import (
+from signac._synced_collections.backends.collection_json import (
     BufferedJSONAttrDict,
     BufferedJSONAttrList,
     BufferedJSONDict,
@@ -21,7 +21,7 @@
     MemoryBufferedJSONDict,
     MemoryBufferedJSONList,
 )
-from signac.synced_collections.errors import BufferedError, MetadataError
+from signac._synced_collections.errors import BufferedError, MetadataError
 
 
 class BufferedJSONCollectionTest(JSONCollectionTest):

tests/test_synced_collections/test_json_collection.py

@@ -8,7 +8,7 @@
 from attr_dict_test import AttrDictTest, AttrListTest
 from synced_collection_test import SyncedDictTest, SyncedListTest
 
-from signac.synced_collections.backends.collection_json import (
+from signac._synced_collections.backends.collection_json import (
     JSONAttrDict,
     JSONAttrList,
     JSONDict,

tests/test_synced_collections/test_mongodb_collection.py

@@ -4,7 +4,7 @@
 import pytest
 from synced_collection_test import SyncedDictTest, SyncedListTest
 
-from signac.synced_collections.backends.collection_mongodb import (
+from signac._synced_collections.backends.collection_mongodb import (
     MongoDBDict,
     MongoDBList,
 )

tests/test_synced_collections/test_redis_collection.py

@@ -7,7 +7,7 @@
 import pytest
 from synced_collection_test import SyncedDictTest, SyncedListTest
 
-from signac.synced_collections.backends.collection_redis import RedisDict, RedisList
+from signac._synced_collections.backends.collection_redis import RedisDict, RedisList
 
 try:
     import redis

tests/test_synced_collections/test_utils.py

@@ -7,10 +7,10 @@
 
 import pytest
 
-from signac.synced_collections import SyncedList
-from signac.synced_collections.backends.collection_json import JSONDict
-from signac.synced_collections.numpy_utils import NumpyConversionWarning
-from signac.synced_collections.utils import (
+from signac._synced_collections import SyncedList
+from signac._synced_collections.backends.collection_json import JSONDict
+from signac._synced_collections.numpy_utils import NumpyConversionWarning
+from signac._synced_collections.utils import (
     AbstractTypeResolver,
     SyncedCollectionJSONEncoder,
 )

tests/test_synced_collections/test_validators.py

@@ -3,8 +3,8 @@
 # This software is licensed under the BSD 3-Clause License.
 import pytest
 
-from signac.synced_collections.errors import InvalidKeyError, KeyTypeError
-from signac.synced_collections.validators import (
+from signac._synced_collections.errors import InvalidKeyError, KeyTypeError
+from signac._synced_collections.validators import (
     json_format_validator,
     no_dot_in_key,
     require_string_key,