source: Doctests for BaseSource using MemorySource

Signed-off-by: Hashim.git <[email protected]>

Author: mhash1m

CHANGELOG.md

@@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `dffml.dataflow.run` operation.
 - Support for operations without inputs.
 - Partial doctestable examples to `features.py`
+- Doctestable examples for `BaseSource`
 ### Fixed
 - New model tutorial mentions file paths that should be edited.
 - DataFlow is no longer a dataclass to prevent it from being exported

dffml/source/source.py

@@ -29,20 +29,64 @@ def __init__(self, parent: "BaseSource") -> None:
     async def update(self, record: Record):
         """
         Updates a record for a source
+
+        Examples
+        --------
+        >>> async def main():
+        ...     async with MemorySource(records=[]) as source:
+        ...         # Open, update, and close
+        ...         async with source() as ctx:
+        ...             example = Record("one", data=dict(features=dict(feed="face")))
+        ...             # ... Update one into our records ...
+        ...             await ctx.update(example)
+        ...             # Let's check out our records after calling `record` and `update`.
+        ...             async for record in ctx.records():
+        ...                 print(record.export())
+        >>>
+        >>> asyncio.run(main())
+        {'key': 'one', 'features': {'feed': 'face'}, 'extra': {}}
         """
 
     @abc.abstractmethod
     async def records(self) -> AsyncIterator[Record]:
         """
         Returns a list of records retrieved from self.src
+
+        Examples
+        --------
+        >>> async def main():
+        ...     async with MemorySource(records=[Record("example", data=dict(features=dict(dead="beef")))]) as source:
+        ...         async with source() as ctx:
+        ...             async for record in ctx.records():
+        ...                 print(record.export())
+        >>>
+        >>> asyncio.run(main())
+        {'key': 'example', 'features': {'dead': 'beef'}, 'extra': {}}
         """
         # mypy ignores AsyncIterator[Record], therefore this is needed
         yield Record("")  # pragma: no cover
 
     @abc.abstractmethod
     async def record(self, key: str):
         """
-        Get a record from the source or add it if it doesn't exist
+        Get a record from the source or add it if it doesn't exist.
+
+        Examples
+        --------
+        >>> async def main():
+        ...     async with MemorySource(records=[Record("example", data=dict(features=dict(dead="beef")))]) as source:
+        ...         # Open, update, and close
+        ...         async with source() as ctx:
+        ...             example = await ctx.record("example")
+        ...             # Let's also try calling `record` for a record that doesnt exist.
+        ...             one = await ctx.record("one")
+        ...             await ctx.update(one)
+        ...             async for record in ctx.records():
+        ...                 print(record.export())
+        >>>
+        >>> asyncio.run(main())
+        {'key': 'example', 'features': {'dead': 'beef'}, 'extra': {}}
+        {'key': 'one', 'extra': {}}
         """
 
 

docs/doctest_header.py

@@ -17,12 +17,13 @@
 os.chdir(DOCTEST_TEMPDIR)
 
 from dffml_model_scikit import *
-from dffml.record import RecordPrediction, RecordData, Record
 from dffml import *
 from dffml.base import *
+from dffml.record import *
 from dffml.df.base import *
 from dffml.df.types import *
 from dffml.df.memory import *
 from dffml.util.net import *
 from dffml.operation.output import *
 from dffml.operation.dataflow import *
+from dffml.source.memory import *