doc: add the missing docstrings

Author: azmeuk

src/scim2_sqlalchemy/comparison.py

@@ -81,6 +81,7 @@ class _Normalizer(_Comparator):
     """
 
     def _form(self, column: _Column, expression: Any) -> ColumnElement[Any]:
+        """Normalize a string expression to NFC, lowered if the column ignores the case, under the C collation."""
         normalized = func.normalize(expression, literal_column("NFC"), type_=String)
         if column.casefolded:
             normalized = func.normalize(
@@ -89,9 +90,11 @@ def _form(self, column: _Column, expression: Any) -> ColumnElement[Any]:
         return normalized.collate("C")
 
     def column(self, column: _Column) -> ColumnElement[Any]:
+        """Return a string column normalized to NFC."""
         return self._form(column, column.compared)
 
     def operand(self, column: _Column, value: str) -> Any:
+        """Return a string normalized to NFC, in Python then in the database."""
         return self._form(column, literal(unicodedata.normalize("NFC", value)))
 
 
@@ -112,12 +115,15 @@ def __init__(self, policy: ScimPolicy, mappings: Iterable[ResourceMapping]):
         }
 
     def prepare(self, connection: Any) -> None:
+        """Register the comparison key as a SQL function of a DBAPI connection."""
         connection.create_function(_KEY_FUNCTION, 2, self.key, deterministic=True)
 
     async def prepare_async(self, connection: Any) -> None:
+        """Register the comparison key as a SQL function of an asyncio DBAPI connection."""
         await connection.create_function(_KEY_FUNCTION, 2, self.key, deterministic=True)
 
     def key(self, urn: str, value: Any) -> Any:
+        """Return the comparison key of a stored value, or None if the key refuses it."""
         if value is None:
             return None
         try:
@@ -126,17 +132,20 @@ def key(self, urn: str, value: Any) -> Any:
             return None
 
     def column(self, column: _Column) -> ColumnElement[Any]:
+        """Return the comparison key of a string column, computed by the SQL function."""
         key: ColumnElement[Any] = getattr(func, _KEY_FUNCTION)(
             literal(column.binding.urn), column.compared, type_=String
         )
         return key
 
     def operand(self, column: _Column, value: str) -> Any:
+        """Return the comparison key of a string, computed in Python."""
         return column.binding.comparable(value, self.policy)
 
     def substring(
         self, op: CompareOperator, column: _Column, value: str
     ) -> ColumnElement[bool]:
+        """Return whether a string column contains, starts or ends with a value, compared by their keys."""
         left = self.column(column)
         right = literal(self.operand(column, value))
         if op == CompareOperator.co:

src/scim2_sqlalchemy/conversion.py

@@ -44,6 +44,7 @@ def _as_stored(value: Any) -> Any:
 
 
 def _read(column: _Column, record: Any) -> Any:
+    """Return the SCIM value of a column of a record, or None if the column is not read."""
     value = getattr(record, column.key)
     if value is None or not column.readable:
         return None
@@ -53,6 +54,7 @@ def _read(column: _Column, record: Any) -> Any:
 
 
 def _version(mapping: ResourceMapping, record: Any) -> str:
+    """Return the weak ETag of the version of a record."""
     return f'W/"{getattr(record, mapping._version.key)}"'
 
 
@@ -180,6 +182,7 @@ def _from_scim(
 
 
 def _write_entry(collection: _Collection, entry: Any) -> Any:
+    """Build the record storing an entry of a multi-valued attribute."""
     record = collection.entry_class()
     if collection.simple:
         setattr(record, collection.columns[None].key, _as_stored(entry))

src/scim2_sqlalchemy/mapping.py

@@ -50,6 +50,7 @@ class _Storage(Enum):
 
 
 def _holds_text(expression: Any) -> bool:
+    """Whether an expression holds strings. A type that tells no Python type is taken as text."""
     try:
         return expression.type.python_type is str
     except NotImplementedError:
@@ -183,6 +184,7 @@ class _Column:
 
     @property
     def is_string(self) -> bool:
+        """Whether the attribute is a SCIM string."""
         target = self.binding.target_type
         return (
             target is not None
@@ -251,22 +253,27 @@ class _Collection:
 
     @property
     def owned(self) -> bool:
+        """Whether the entries belong to the resource, rather than link to other resources."""
         return self.resource_type is None
 
     @property
     def entry_class(self) -> type[Any]:
+        """The SQLAlchemy model of the entries."""
         return self.relationship_property.mapper.class_
 
     @property
     def relationship_property(self) -> RelationshipProperty[Any]:
+        """The relationship holding the entries."""
         return self.relationship.property  # type: ignore[return-value]
 
     @property
     def single(self) -> bool:
+        """Whether the collection holds one entry at most."""
         return not self.binding.is_multivalued
 
     @property
     def simple(self) -> bool:
+        """Whether the collection holds the values of a multi-valued simple attribute."""
         return None in self.columns
 
     def column(self, sub_field_name: str | None) -> _Column | None:
@@ -363,6 +370,7 @@ def schemas(self) -> list[Schema]:
         return [self._restrict(model.to_schema()) for model in models]
 
     def _restrict(self, schema: Schema) -> Schema:
+        """Return a schema with the attributes the mapping stores only."""
         attributes = []
         for attribute in schema.attributes or []:
             restricted = self._restrict_attribute(
@@ -458,6 +466,7 @@ def _all_collections(self) -> Iterator[_Collection]:
             yield from collections
 
     def _column(self, path: str) -> _Column:
+        """Return the column of the attribute at a path."""
         binding = self._resolve(path)
         return self._columns[
             (binding.model, binding.field_name, binding.sub_field_name)
@@ -596,15 +605,18 @@ def _display(self) -> _Column | None:
         return None
 
     def _find(self, path: str) -> AttributeBinding | None:
+        """Return the attribute at a path, or None if the model has none there."""
         return Path[self.model](path).resolve()  # type: ignore[name-defined]
 
     def _resolve(self, path: str) -> AttributeBinding:
+        """Return the attribute at a path, refusing a path the model does not know."""
         binding = self._find(path)
         if binding is None:
             raise ValueError(f"{path!r} is not an attribute of {self.model.__name__}")
         return binding
 
     def _add(self, path: str, value: Any) -> None:
+        """Check the mapping of the attribute at a path, and keep its column or its collections."""
         binding = self._resolve(path)
         target = binding.target_type
         is_complex = isclass(target) and issubclass(target, BaseModel)

src/scim2_sqlalchemy/query.py

@@ -81,6 +81,7 @@ def _exact_key(column: _Column, value: str) -> Any:
 
 
 def _unmapped(binding: AttributeBinding) -> InvalidFilterException:
+    """Return the error of a filter on an attribute the mapping does not let filters read."""
     return InvalidFilterException(detail=f"Cannot filter on '{binding.urn}'")
 
 
@@ -156,11 +157,16 @@ def _targets(
     def _in_collection(
         self, collection: _Collection | None, condition: ColumnElement[bool]
     ) -> ColumnElement[bool]:
+        """Apply a condition to the entries of a collection, or to the record itself outside of any collection.
+
+        Within a value selection, the condition already applies to the entries.
+        """
         if collection is None or self.scope is not None:
             return condition
         return collection.exists(condition)
 
     def visit_comparison(self, node: Comparison) -> ColumnElement[bool]:
+        """Keep the records with a value matching the comparison, in any collection holding the attribute."""
         binding = self._resolve(node.attr_path, self.filter.resolve_comparison)
         if binding is None:
             return false()
@@ -194,6 +200,10 @@ def visit_comparison(self, node: Comparison) -> ColumnElement[bool]:
         )
 
     def visit_present(self, node: Present) -> ColumnElement[bool]:
+        """Keep the records with a value for the attribute.
+
+        A complex attribute is present when one of its sub-attributes is.
+        """
         binding = self._resolve(node.attr_path, self.filter.resolve)
         if binding is None:
             return false()
@@ -217,13 +227,16 @@ def visit_present(self, node: Present) -> ColumnElement[bool]:
         return or_(*(_present(column) for column in sub_columns))
 
     def visit_not(self, node: Not) -> ColumnElement[bool]:
+        """Keep the records the inner filter does not keep."""
         return not_(self.visit(node.expr))
 
     def visit_logical_expr(self, node: LogicalExpr) -> ColumnElement[bool]:
+        """Combine the conditions of the terms with AND or OR."""
         combine = and_ if node.op == LogicalOperator.and_ else or_
         return combine(*(self.visit(term) for term in node.terms))
 
     def visit_value_path(self, node: ValuePath) -> ColumnElement[bool]:
+        """Keep the records with an entry of the attribute matching the inner filter."""
         binding = self.filter.resolve(node.attr_path, strict=False)
         if binding is None:
             return false()
@@ -361,6 +374,7 @@ def _where(
     search_request: SearchRequest[Any],
     comparator: _Comparator,
 ) -> ColumnElement[bool]:
+    """Return the condition keeping the records matching the filter of a search, or every record without filter."""
     if search_request.filter is None:
         return true()
     scim_filter = ScimFilter[mapping.model](str(search_request.filter))  # type: ignore[name-defined]
@@ -375,6 +389,7 @@ def _cursor_page(page: Select[Any], search_request: SearchRequest[Any]) -> Selec
 
 
 def _index_page(page: Select[Any], search_request: SearchRequest[Any]) -> Select[Any]:
+    """Limit a page to the records from startIndex, at most count of them."""
     page = page.offset(search_request.start_index_0 or 0)
     if search_request.count is None:
         return page

src/scim2_sqlalchemy/storage.py

@@ -52,6 +52,7 @@
 
 
 def _utcnow() -> datetime.datetime:
+    """Return the current time, in UTC."""
     return datetime.datetime.now(datetime.UTC)
 
 
@@ -129,11 +130,11 @@ def _cursor_page(
 
 
 def _nothing() -> None:
-    pass
+    """Check nothing, as the default uniqueness check of a flush."""
 
 
 async def _nothing_async() -> None:
-    pass
+    """Check nothing, as the default uniqueness check of a flush."""
 
 
 class _StorageBase:
@@ -156,6 +157,7 @@ def __init__(
             mapping._bind(self.mappings)
 
     def _mapping(self, resource_type: ResourceType) -> ResourceMapping:
+        """Return the mapping of a resource type."""
         return self.mappings[resource_type.name]  # type: ignore[index]
 
     def _root_page(
@@ -253,6 +255,7 @@ def _check_storable(
     def _not_found(
         resource_type: ResourceType, resource_id: str | None
     ) -> NotFoundException:
+        """Return the error of a resource that does not exist."""
         return NotFoundException(
             detail=f"{resource_type.name} {resource_id!r} not found"
         )
@@ -261,6 +264,7 @@ def _not_found(
     def _check_version(
         mapping: ResourceMapping, record: Any, expected_version: str | None
     ) -> None:
+        """Refuse to change a record whose version is not the expected one."""
         if (
             expected_version is not None
             and _version(mapping, record) != expected_version
@@ -421,6 +425,7 @@ def get(
         *,
         response_parameters: ResponseParameters[Any] | None = None,
     ) -> Resource[Any]:
+        """Return a resource, with the attributes the response keeps."""
         record = self._load(resource_type, resource_id, response_parameters)
         return self._to_scim(resource_type, record, response_parameters)
 
@@ -431,6 +436,7 @@ def search(
         *,
         position: Any = None,
     ) -> SearchPage:
+        """Return a page of the resources matching a search, on one resource type or at the root."""
         if not resource_types:
             return SearchPage(0, [])
         session = self.session()
@@ -464,6 +470,7 @@ def search(
     def create(
         self, resource_type: ResourceType, resource: Resource[Any]
     ) -> Resource[Any]:
+        """Store a new resource, and return it as stored."""
         mapping = self._mapping(resource_type)
         self._check_storable(resource_type, resource, None)
         self._check_uniqueness(mapping, resource)
@@ -484,6 +491,7 @@ def update(
         *,
         expected_version: str | None = None,
     ) -> Resource[Any]:
+        """Replace a resource, and return it as stored."""
         mapping = self._mapping(resource_type)
         record = self._load(resource_type, resource.id)
         self._check_version(mapping, record, expected_version)
@@ -503,6 +511,7 @@ def delete(
         *,
         expected_version: str | None = None,
     ) -> None:
+        """Delete a resource."""
         mapping = self._mapping(resource_type)
         record = self._load(resource_type, resource_id)
         self._check_version(mapping, record, expected_version)
@@ -526,6 +535,7 @@ def _load(
     def _check_uniqueness(
         self, mapping: ResourceMapping, resource: Resource[Any]
     ) -> None:
+        """Refuse a resource with a unique value another resource already has."""
         session = self.session()
         comparator = self._ready_comparator(session)
         for statement in self._unique_statements(mapping, resource, comparator):
@@ -542,6 +552,7 @@ def _ready_comparator(self, session: Session) -> _Comparator:
     def _links(
         self, mapping: ResourceMapping, resource: Resource[Any]
     ) -> dict[_Collection, list[Any]]:
+        """Return the records each Link of a resource links to, refusing a value that links to nothing."""
         links: dict[_Collection, list[Any]] = {}
         for collections, entries in _link_entries(mapping, resource):
             ids = [entry.value for entry in entries]
@@ -620,6 +631,7 @@ async def get(
         *,
         response_parameters: ResponseParameters[Any] | None = None,
     ) -> Resource[Any]:
+        """Return a resource, with the attributes the response keeps."""
         record = await self._load(resource_type, resource_id, response_parameters)
         return self._to_scim(resource_type, record, response_parameters)
 
@@ -630,6 +642,7 @@ async def search(
         *,
         position: Any = None,
     ) -> SearchPage:
+        """Return a page of the resources matching a search, on one resource type or at the root."""
         if not resource_types:
             return SearchPage(0, [])
         session = self.session()
@@ -663,6 +676,7 @@ async def search(
     async def create(
         self, resource_type: ResourceType, resource: Resource[Any]
     ) -> Resource[Any]:
+        """Store a new resource, and return it as stored."""
         mapping = self._mapping(resource_type)
         self._check_storable(resource_type, resource, None)
         await self._check_uniqueness(mapping, resource)
@@ -683,6 +697,7 @@ async def update(
         *,
         expected_version: str | None = None,
     ) -> Resource[Any]:
+        """Replace a resource, and return it as stored."""
         mapping = self._mapping(resource_type)
         record = await self._load(resource_type, resource.id)
         self._check_version(mapping, record, expected_version)
@@ -703,6 +718,7 @@ async def delete(
         *,
         expected_version: str | None = None,
     ) -> None:
+        """Delete a resource."""
         mapping = self._mapping(resource_type)
         record = await self._load(resource_type, resource_id)
         self._check_version(mapping, record, expected_version)
@@ -730,6 +746,7 @@ async def _load(
     async def _check_uniqueness(
         self, mapping: ResourceMapping, resource: Resource[Any]
     ) -> None:
+        """Refuse a resource with a unique value another resource already has."""
         session = self.session()
         comparator = await self._ready_comparator(session)
         for statement in self._unique_statements(mapping, resource, comparator):
@@ -747,6 +764,7 @@ async def _ready_comparator(self, session: AsyncSession) -> _Comparator:
     async def _links(
         self, mapping: ResourceMapping, resource: Resource[Any]
     ) -> dict[_Collection, list[Any]]:
+        """Return the records each Link of a resource links to, refusing a value that links to nothing."""
         links: dict[_Collection, list[Any]] = {}
         for collections, entries in _link_entries(mapping, resource):
             ids = [entry.value for entry in entries]