fix: Exposed submodules in fastcs.__init__ (#139)

* We can avoid circular imports in typing by importing from the module.

* Also added docstrings so api parsing passes

Author: evvaaaa

docs/conf.py

@@ -71,10 +71,27 @@
     ("py:class", "'object'"),
     ("py:class", "'id'"),
     ("py:class", "typing_extensions.Literal"),
+    # Doesn't work even with asyncio intersphinx mapping
+    ("py:class", "asyncio.events.AbstractEventLoop"),
+    ("py:class", "asyncio.streams.StreamReader"),
+    ("py:class", "asyncio.streams.StreamWriter"),
+    # Annoying error:
+    #     docstring of collections.abc.Callable:1: WARNING:
+    #     'any' reference target not found: self [ref.any]
+    ("any", "self"),
+    # p4p doesn't have intersphinx mapping
+    ("py:class", "p4p.server.StaticProvider"),
+    ("py:class", "p4p.nt.scalar.NTScalar"),
+    ("py:class", "p4p.nt.enum.NTEnum"),
+    ("py:class", "p4p.nt.ndarray.NTNDArray"),
+    ("py:class", "p4p.nt.NTTable"),
+    # Problems in FastCS itself
+    ("py:class", "fastcs.transport.epics.pva.pvi_tree._PviSignalInfo"),
+    # TypeVar without docstrings still give warnings
+    ("py:class", "fastcs.datatypes.T_Numerical"),
+    ("py:class", "strawberry.schema.schema.Schema"),
 ]
-nitpick_ignore_regex = [
-    ("py:class", "fastcs.*.T"),
-]
+nitpick_ignore_regex = [("py:class", "fastcs.*.T")]
 
 # Both the class’ and the __init__ method’s docstring are concatenated and
 # inserted into the main body of the autoclass directive
@@ -112,7 +129,9 @@
 
 # This means you can link things like `str` and `asyncio` to the relevant
 # docs in the python documentation.
-intersphinx_mapping = {"python": ("https://docs.python.org/3/", None)}
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+}
 
 # A dictionary of graphviz graph attributes for inheritance diagrams.
 inheritance_graph_attrs = {"rankdir": "TB"}

src/fastcs/__init__.py

@@ -6,8 +6,10 @@
     Version number as calculated by https://github.com/pypa/setuptools_scm
 """
 
-from ._version import __version__
+from . import attributes as attributes
+from . import controller as controller
+from . import cs_methods as cs_methods
+from . import datatypes as datatypes
+from . import transport as transport
+from ._version import __version__ as __version__
 from .launch import FastCS as FastCS
-from .launch import launch as launch
-
-__all__ = ["__version__"]

src/fastcs/attributes.py

@@ -5,6 +5,8 @@
 from enum import Enum
 from typing import Any, Generic, Protocol, runtime_checkable
 
+import fastcs
+
 from .datatypes import ATTRIBUTE_TYPES, AttrCallback, DataType, T
 
 
@@ -20,7 +22,9 @@ class AttrMode(Enum):
 class Sender(Protocol):
     """Protocol for setting the value of an ``Attribute``."""
 
-    async def put(self, controller: Any, attr: AttrW, value: Any) -> None:
+    async def put(
+        self, controller: fastcs.controller.BaseController, attr: AttrW, value: Any
+    ) -> None:
         pass
 
 
@@ -31,7 +35,9 @@ class Updater(Protocol):
     # If update period is None then the attribute will not be updated as a task.
     update_period: float | None = None
 
-    async def update(self, controller: Any, attr: AttrR) -> None:
+    async def update(
+        self, controller: fastcs.controller.BaseController, attr: AttrR
+    ) -> None:
         pass
 
 
@@ -45,7 +51,9 @@ class Handler(Sender, Updater, Protocol):
 class SimpleHandler(Handler):
     """Handler for internal parameters"""
 
-    async def put(self, controller: Any, attr: AttrW, value: Any):
+    async def put(
+        self, controller: fastcs.controller.BaseController, attr: AttrW, value: Any
+    ):
         await attr.update_display_without_process(value)
 
         if isinstance(attr, AttrRW):

src/fastcs/backend.py

@@ -11,6 +11,8 @@
 
 
 class Backend:
+    """For keeping track of tasks during FastCS serving."""
+
     def __init__(
         self,
         controller: Controller,
@@ -163,6 +165,7 @@ async def scan_coro() -> None:
 
 
 def build_controller_api(controller: Controller) -> ControllerAPI:
+    """Build a `ControllerAPI` for a `BaseController` and its sub controllers"""
     return _build_controller_api(controller, [])
 
 

src/fastcs/connections/ip_connection.py

@@ -3,6 +3,8 @@
 
 
 class DisconnectedError(Exception):
+    """Raised if the ip connection is disconnected."""
+
     pass
 
 
@@ -14,6 +16,8 @@ class IPConnectionSettings:
 
 @dataclass
 class StreamConnection:
+    """For reading and writing to a stream."""
+
     reader: asyncio.StreamReader
     writer: asyncio.StreamWriter
 
@@ -41,6 +45,8 @@ async def close(self):
 
 
 class IPConnection:
+    """For connecting to an ip using a `StreamConnection`."""
+
     def __init__(self):
         self.__connection = None
 

src/fastcs/connections/serial_connection.py

@@ -5,6 +5,8 @@
 
 
 class NotOpenedError(Exception):
+    """If the serial stream is not opened."""
+
     pass
 
 
@@ -15,6 +17,8 @@ class SerialConnectionSettings:
 
 
 class SerialConnection:
+    """A serial connection."""
+
     def __init__(self):
         self.stream = None
         self._lock = asyncio.Lock()

src/fastcs/controller.py

@@ -7,6 +7,8 @@
 
 
 class BaseController:
+    """Base class for controller."""
+
     #: Attributes passed from the device at runtime.
     attributes: dict[str, Attribute]
 
@@ -29,7 +31,7 @@ def __init__(
 
     @property
     def path(self) -> list[str]:
-        """Path prefix of attributes, recursively including parent ``Controller``s."""
+        """Path prefix of attributes, recursively including parent Controllers."""
         return self._path
 
     def set_path(self, path: list[str]):

src/fastcs/controller_api.py

@@ -20,10 +20,10 @@ class ControllerAPI:
     description: str | None = None
 
     def walk_api(self) -> Iterator["ControllerAPI"]:
-        """Walk through all the nested `ControllerAPIs` of this `ControllerAPI`
+        """Walk through all the nested `ControllerAPI` s of this `ControllerAPI`.
 
-        yields: `ControllerAPI`s from a depth-first traversal of the tree, including
-        self.
+        Yields the `ControllerAPI` s from a depth-first traversal of the tree,
+        including self.
 
         """
         yield self

src/fastcs/cs_methods.py

@@ -123,6 +123,8 @@ async def __call__(self):
 
 
 class Put(Method[BaseController]):
+    """Why don't know what this is for."""
+
     def __init__(self, fn: PutCallback):
         super().__init__(fn)
 
@@ -142,7 +144,7 @@ class UnboundCommand(Method[Controller_T]):
     This generic class stores an unbound `Controller` method - effectively a function
     that takes an instance of a specific `Controller` type (`Controller_T`). Instances
     of this class can be added at `Controller` definition, either manually or with use
-    of the `@command` wrapper, to register the method to be included in the API of the
+    of the `command` wrapper, to register the method to be included in the API of the
     `Controller`. When the `Controller` is instantiated, these instances will be bound
     to the instance, creating a `Command` instance.
     """
@@ -171,7 +173,7 @@ class UnboundScan(Method[Controller_T]):
     This generic class stores an unbound `Controller` method - effectively a function
     that takes an instance of a specific `Controller` type (`Controller_T`). Instances
     of this class can be added at `Controller` definition, either manually or with use
-    of the `@scan` wrapper, to register the method to be included in the API of the
+    of the `scan` wrapper, to register the method to be included in the API of the
     `Controller`. When the `Controller` is instantiated, these instances will be bound
     to the instance, creating a `Scan` instance.
     """
@@ -199,6 +201,8 @@ def __call__(self):
 
 
 class UnboundPut(Method[Controller_T]):
+    """Unbound version of `Put`."""
+
     def __init__(self, fn: UnboundPutCallback[Controller_T]) -> None:
         super().__init__(fn)
 

src/fastcs/exceptions.py

@@ -1,6 +1,8 @@
 class FastCSException(Exception):
-    pass
+    """Base class for general problems in the running of a FastCS transport."""
 
 
 class LaunchError(FastCSException):
-    pass
+    """For when there is an error in launching FastCS with the given
+    transports and controller.
+    """