Office365-REST-Python-Client 3.0.0__py3-none-any.whl → 3.1.0__py3-none-any.whl

office365/runtime/parallel.py

@@ -0,0 +1,96 @@
+"""Generic parallel execution — run a worker across tasks on a thread pool.
+
+Centralizes the thread-pool + per-worker context + shared rate-limiting +
+result/error contract so callers don't re-implement it (parallel batch
+execution, the migration uploader, ...). Each worker thread lazily creates one
+context via ``context_factory`` (e.g. a ``ClientContext.clone``) and, when a
+shared :class:`RateLimiter` is given, binds it so the whole fleet paces as a
+group on ``Retry-After`` / ``X-SharePointHealthScore``.
+"""
+
+from __future__ import annotations
+
+import threading
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import TYPE_CHECKING, Any, Callable, Iterable, List, Optional
+
+from office365.runtime.http.throttling import RateLimiter
+
+if TYPE_CHECKING:
+    from office365.runtime.client_runtime_context import ClientRuntimeContext
+
+
+def run_parallel(
+    worker: Callable[[Optional["ClientRuntimeContext"], Any], Any],
+    tasks: Iterable[Any],
+    *,
+    concurrency: int = 4,
+    context_factory: Optional[Callable[[], Optional["ClientRuntimeContext"]]] = None,
+    limiter: Optional[RateLimiter] = None,
+    progress: Optional[Callable[[Any], None]] = None,
+    on_error: Optional[Callable[[Any, Exception], Any]] = None,
+) -> List[Any]:
+    """Run ``worker(context, task)`` for each task on a thread pool.
+
+    Args:
+        worker: Callable invoked once per task with the worker's context (a
+          lazily-created per-thread context from ``context_factory``, or None)
+          and the task payload.
+        tasks: Iterable of task payloads (results are returned in this order).
+        concurrency: Maximum number of concurrent worker threads.
+        context_factory: Optional zero-arg callable returning a context for each
+          worker thread (created once per thread and reused). When a limiter is
+          given it is bound to every produced context.
+        limiter: Optional shared :class:`RateLimiter` for fleet pacing; when
+          ``context_factory`` is given one is created automatically.
+        progress: Optional hook fired per completed task with a ``Progress``
+          snapshot (``done``/``total``).
+        on_error: Optional ``(task, error) -> fallback`` handler; when absent a
+          task failure re-raises from the pool.
+
+    Returns:
+        Worker results in input order (a failed task yields its ``on_error``
+        fallback, or raises).
+    """
+    tasks = list(tasks)
+    if not tasks:
+        return []
+
+    if limiter is None and context_factory is not None:
+        limiter = RateLimiter()
+    results: List[Any] = [None] * len(tasks)
+    local = threading.local()
+    lock = threading.Lock()
+    done = {"count": 0}
+
+    def _context() -> Optional["ClientRuntimeContext"]:
+        ctx = getattr(local, "context", None)
+        if ctx is None and callable(context_factory):
+            ctx = context_factory()
+            if ctx is not None and limiter is not None:
+                limiter.bind(ctx)
+            local.context = ctx
+        return ctx
+
+    def _run(index: int, task: Any) -> None:
+        try:
+            results[index] = worker(_context(), task)
+        except Exception as e:  # noqa: BLE001 — per-task errors handled by on_error
+            if callable(on_error):
+                results[index] = on_error(task, e)
+            else:
+                raise
+        finally:
+            with lock:
+                done["count"] += 1
+                n = done["count"]
+        if callable(progress):
+            from office365.runtime.operations import Progress
+
+            progress(Progress(done=n, total=len(tasks), stage="parallel"))
+
+    with ThreadPoolExecutor(max_workers=concurrency) as executor:
+        futures = [executor.submit(_run, index, task) for index, task in enumerate(tasks)]
+        for future in as_completed(futures):
+            future.result()
+    return results

office365/runtime/paths/builder.py

@@ -13,11 +13,13 @@ if TYPE_CHECKING:
 class ODataPathBuilder:
     """A builder for constructing OData paths with proper encoding and URL handling."""
 
-    # Characters that need special handling in OData URLs
+    # Characters that need special handling in OData URLs.
+    # NOTE: "/" is intentionally *not* encoded — slashes are valid inside OData
+    # string literals, and encoding them inflates path-based URLs (~3x) enough to
+    # hit SharePoint's URL length limit for deep folder structures.
     _SPECIAL_CHARS = {
         "%": "%25",
         "+": "%2B",
-        "/": "%2F",
         "?": "%3F",
         "#": "%23",
         "&": "%26",

office365/runtime/queries/batch.py

@@ -1,12 +1,13 @@
 from __future__ import annotations
 
 import uuid
+from typing import Any, Generic
 
 from typing_extensions import Self
 
 from office365.runtime.client_runtime_context import ClientRuntimeContext
 from office365.runtime.queries.client_query import ClientQuery, ReturnT
-from office365.runtime.queries.noop import NoOpQuery
+from office365.runtime.queries.deferred import DeferredOperationQuery
 from office365.runtime.queries.read_entity import ReadEntityQuery
 
 
@@ -23,10 +24,10 @@ def create_boundary(prefix: str, compact: bool = False) -> str:
         return prefix + str(uuid.uuid4())
 
 
-class BatchQuery(ClientQuery[ReturnT]):
+class BatchQuery(ClientQuery[Any], Generic[ReturnT]):
     """Client query collection for batch requests."""
 
-    def __init__(self, context: ClientRuntimeContext, queries: list[ClientQuery] | None = None) -> None:
+    def __init__(self, context: ClientRuntimeContext, queries: list[ClientQuery[Any]] | None = None) -> None:
         """
         Initialize a batch query collection.
 
@@ -38,9 +39,9 @@ class BatchQuery(ClientQuery[ReturnT]):
         self._current_boundary = create_boundary("batch_")
         if queries is None:
             queries = []
-        self._queries = queries
+        self._queries: list[ClientQuery[Any]] = queries
 
-    def add(self, query: ClientQuery) -> Self:
+    def add(self, query: ClientQuery[Any]) -> Self:
         """Add a query to the batch.
 
         Args:
@@ -50,7 +51,7 @@ class BatchQuery(ClientQuery[ReturnT]):
         return self
 
     @property
-    def ordered_queries(self) -> list[ClientQuery]:
+    def ordered_queries(self) -> list[ClientQuery[Any]]:
         """Returns all queries in execution order (change sets first, then GET queries)."""
         return self.change_sets + self.get_queries
 
@@ -60,19 +61,23 @@ class BatchQuery(ClientQuery[ReturnT]):
         return self._current_boundary
 
     @property
-    def change_sets(self) -> list[ClientQuery]:
+    def change_sets(self) -> list[ClientQuery[Any]]:
         """Gets all queries that modify data (non-GET operations)."""
-        return [qry for qry in self._queries if not isinstance(qry, (ReadEntityQuery, NoOpQuery))]
+        return [qry for qry in self._queries if not isinstance(qry, (ReadEntityQuery, DeferredOperationQuery))]
 
     @property
-    def queries(self) -> list[ClientQuery]:
+    def queries(self) -> list[ClientQuery[Any]]:
         """Gets all queries in the batch."""
         return self._queries
 
     @property
-    def get_queries(self) -> list[ClientQuery]:
-        """Gets all read-only (GET) queries in the batch."""
-        return [qry for qry in self._queries if isinstance(qry, (ReadEntityQuery, NoOpQuery))]
+    def get_queries(self) -> list[ClientQuery[Any]]:
+        """Gets all read-only (GET) queries in the batch.
+
+        DeferredOperationQuery placeholders are excluded: they carry no request
+        of their own and resolve as no-ops.
+        """
+        return [qry for qry in self._queries if isinstance(qry, ReadEntityQuery)]
 
     @property
     def has_change_sets(self) -> bool:
@@ -85,6 +90,10 @@ class BatchQuery(ClientQuery[ReturnT]):
         return f"{self.context.service_root_url}/$batch"
 
     @property
-    def return_type(self) -> list[ReturnT]:  # type:ignore
-        """Gets the return types of all queries in the batch."""
+    def return_types(self) -> list[ReturnT]:
+        """Gets the return types of all queries in the batch.
+
+        Named ``return_types`` (not ``return_type``) because a batch's response
+        is a list, while ``ClientQuery.return_type`` describes a single result.
+        """
         return [q.return_type for q in self._queries if q.return_type]

office365/runtime/queries/client_query.py

@@ -10,6 +10,7 @@ from office365.runtime.paths.resource_path import ResourcePath
 
 if TYPE_CHECKING:
     from office365.runtime.client_object import ClientObject
+    from office365.runtime.client_request import ClientRequest
     from office365.runtime.client_result import ClientResult
     from office365.runtime.client_runtime_context import ClientRuntimeContext
     from office365.runtime.client_value import ClientValue
@@ -43,7 +44,7 @@ class ClientQuery(Generic[ReturnT]):
         self._binding_type = binding_type
         self._parameters_type = parameters_type
         self._parameters_name = parameters_name
-        self._return_type = return_type
+        self._return_type: ReturnT | None = return_type
 
     def build_request(self) -> RequestOptions:
         """Builds a request"""
@@ -51,17 +52,14 @@ class ClientQuery(Generic[ReturnT]):
         self.context.pending_request().beforeExecute(request)
         return request
 
-    def execute_query(self) -> ReturnT | None:
-        """Executes the query and returns the result.
+    def execute_query(self, request: "ClientRequest") -> None:
+        """Run this query via the given request.
 
-        Returns:
-            The query result of type T
-
-        Raises:
-            ClientRequestException: If query execution fails
+        The base implementation delegates to the transport (sends the HTTP
+        request); subclasses may override how they execute — e.g.
+        ``DeferredOperationQuery`` resolves without sending a request.
         """
-        self.context.execute_query()
-        return self.return_type
+        request.execute_query(self)
 
     def before_execute(self, action: Callable[[RequestOptions], None], once: bool = True) -> Self:
         """

office365/runtime/queries/deferred.py

@@ -0,0 +1,72 @@
+"""A placeholder query that defers an operation until it resolves.
+
+Implements a lightweight promise: the placeholder occupies a fixed slot in the
+pending queue; when the prerequisite resolves, :meth:`defer` swaps the slot for
+the real operation (e.g. a field create) or :meth:`resolve` drops it. When it
+executes it runs the deferred operation (if any) or resolves as a no-op without
+a request — so anything queued after the placeholder always runs after the
+operation completes, with no queue reordering.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Optional
+
+import requests
+from typing_extensions import Self
+
+from office365.runtime.queries.client_query import ClientQuery
+
+if TYPE_CHECKING:
+    from office365.runtime.client_object import ClientObject
+    from office365.runtime.client_request import ClientRequest
+
+_OK_RESPONSE = requests.Response()
+_OK_RESPONSE.status_code = 200
+
+
+class DeferredOperationQuery(ClientQuery[Any]):
+    """A queue placeholder that resolves to a deferred operation (or a no-op)."""
+
+    def __init__(self, context, return_type: Optional["ClientObject"] = None):
+        super().__init__(context, return_type=return_type)
+        self._deferred: Optional[ClientQuery] = None
+
+    def defer(self, query: ClientQuery) -> Self:
+        """Swap this placeholder's queue slot for the actual operation.
+
+        The operation runs next (in this slot), before anything queued after
+        the placeholder.
+        """
+        self._deferred = query
+        queue = self.context._queries  # type: ignore[attr-defined]
+        try:
+            queue[queue.index(self)] = query
+        except ValueError:
+            pass
+        return self
+
+    def resolve(self) -> None:
+        """Drop this placeholder from the queue (no operation is needed)."""
+        queue = self.context._queries  # type: ignore[attr-defined]
+        try:
+            queue.remove(self)
+        except ValueError:
+            pass
+
+    def execute_query(self, request: "ClientRequest") -> None:
+        """Resolve this placeholder.
+
+        If an operation was deferred, run it (its response fires this
+        placeholder's ``after_execute`` handlers). Otherwise resolve as a
+        no-op — firing the handlers without sending any request.
+        """
+        if self._deferred is not None:
+            request.execute_query(self._deferred)
+        else:
+            request.afterExecute(_OK_RESPONSE)
+
+    @property
+    def deferred_query(self) -> Optional[ClientQuery]:
+        """The attached operation, or ``None`` when not deferred."""
+        return self._deferred

office365/runtime/queries/delete_entity.py

@@ -1,12 +1,12 @@
 from typing import TYPE_CHECKING
 
-from office365.runtime.queries.client_query import ClientQuery
+from office365.runtime.queries.client_query import ClientQuery, ReturnT
 
 if TYPE_CHECKING:
     from office365.runtime.client_object import ClientObject
 
 
-class DeleteEntityQuery(ClientQuery):
+class DeleteEntityQuery(ClientQuery[ReturnT]):
     """A query to delete an entity from the server."""
 
     def __init__(self, delete_type: "ClientObject") -> None:

office365/runtime/queries/function.py

@@ -1,10 +1,15 @@
 from __future__ import annotations
 
+from typing import TYPE_CHECKING, Optional
+
 from office365.runtime.client_object import ClientObject
 from office365.runtime.client_value import ClientValue
 from office365.runtime.paths.service_operation import ServiceOperationPath
 from office365.runtime.queries.client_query import ClientQuery, ReturnT
 
+if TYPE_CHECKING:
+    from office365.runtime.odata.query_options import QueryOptions
+
 
 class FunctionQuery(ClientQuery[ReturnT]):
     """Represents a function call OData query."""
@@ -15,6 +20,7 @@ class FunctionQuery(ClientQuery[ReturnT]):
         method_name: str | None = None,
         method_params: list | dict | ClientValue | None = None,
         return_type: ReturnT | None = None,
+        return_raw_content: bool = False,
     ) -> None:
         """Initialize a function query.
 
@@ -23,11 +29,39 @@ class FunctionQuery(ClientQuery[ReturnT]):
             method_name: The name of the method to call
             method_params: Parameters for the method call
             return_type: The expected return type
+            return_raw_content: When True, the response body is treated as raw content
+                (e.g. file download) rather than parsed as OData JSON.
         """
         super().__init__(binding_type.context, binding_type, None, None, return_type)
         self._path = ServiceOperationPath(method_name or "", method_params, binding_type.resource_path)
+        self._return_raw_content = return_raw_content
+
+    @property
+    def return_raw_content(self) -> bool:
+        """Whether the response should be treated as raw content, not OData JSON."""
+        return self._return_raw_content
+
+    @property
+    def query_options(self) -> Optional["QueryOptions"]:
+        """Query options carried by the function's return collection (if any)."""
+        return self._return_type.query_options if isinstance(self._return_type, ClientObject) else None
+
+    @property
+    def url(self) -> str:
+        """The function URL with any fluent query options appended.
+
+        Function endpoints (e.g. ``getAllMessages``) accept standard OData query
+        options, so ``.filter()/.select()/.top()`` set on the returned
+        collection are forwarded to the request.
+        """
+        url = super().url
+        options = self.query_options
+        if options is not None and not options.is_empty:
+            delimiter = "&" if "?" in url else "?"
+            url = f"{url}{delimiter}{options}"
+        return url
 
-    def __repr__(self) -> str:
+    def __repr__(self):
         return f"FunctionQuery(name={self.name})"
 
     @property

office365/runtime/queries/read_entity.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, List, Optional
+from typing import TYPE_CHECKING, List, Optional, cast
 
 from office365.runtime.client_value import ClientValue
 from office365.runtime.paths.service_operation import ServiceOperationPath
@@ -22,12 +22,31 @@ class ReadEntityQuery(ClientQuery[ReturnT]):
 
     @property
     def query_options(self) -> "QueryOptions":
-        from office365.runtime.odata.query_options_builder import QueryOptionsBuilder
-
         if self._query_options is None:
-            self._query_options = QueryOptionsBuilder.build(self._return_type, self._properties_to_include)  # type: ignore[reportArgumentType]
+            self._query_options = self._build_query_options()
         return self._query_options
 
+    def _build_query_options(self) -> "QueryOptions":
+        """Resolve query options for the return object, expanding the requested properties."""
+        from office365.runtime.client_object import ClientObject
+        from office365.runtime.client_object_collection import ClientObjectCollection
+
+        client_object = cast(ClientObject, self._return_type)
+        query_options = client_object.query_options
+        for name in self._properties_to_include or []:
+            if name in query_options.select:
+                continue
+
+            if isinstance(client_object, ClientObjectCollection):
+                prop = client_object.create_typed_object().get_property(name)
+            else:
+                prop = client_object.get_property(name)
+
+            if name == "Properties" or isinstance(prop, ClientObject):
+                query_options.expand.append(name)
+            query_options.select.append(name)
+        return query_options
+
     @property
     def url(self) -> str:
         assert self.binding_type is not None

office365/runtime/queries/update_entity.py

@@ -1,8 +1,8 @@
 from office365.runtime.client_object import ClientObject
-from office365.runtime.queries.client_query import ClientQuery
+from office365.runtime.queries.client_query import ClientQuery, ReturnT
 
 
-class UpdateEntityQuery(ClientQuery):
+class UpdateEntityQuery(ClientQuery[ReturnT]):
     """Represents an OData update operation for modifying an existing entity.
 
     This query type is used to construct and execute PATCH or PUT operations

office365/runtime/queries/upload_session.py

@@ -5,7 +5,7 @@ from office365.runtime.odata.v4.upload_session import UploadSession
 from office365.runtime.queries.service_operation import ServiceOperationQuery
 
 
-class UploadSessionQuery(ServiceOperationQuery):
+class UploadSessionQuery(ServiceOperationQuery[ClientResult[UploadSession]]):
     """
     The UploadSession query provides information about how to upload large files to OneDrive, OneDrive for
     Business, or SharePoint document libraries

office365/runtime/retry.py

@@ -0,0 +1,137 @@
+"""Generic retry with exponential backoff + jitter — reusable, first-class retry helper.
+
+Follows the Microsoft Graph / SharePoint guidance: honor the server's
+``Retry-After`` header when present, otherwise back off exponentially with
+jitter (so a fleet of clients doesn't retry in lock-step).
+"""
+
+from __future__ import annotations
+
+import random
+from time import sleep
+from typing import Any, Callable, Optional, Tuple, Type
+
+from office365.runtime.client_request_exception import ClientRequestException
+
+TRANSIENT_STATUS_CODES = frozenset({408, 429, 500, 502, 503, 504})
+
+
+def is_transient_error(ex: Exception) -> bool:
+    """Whether an exception reflects a transient failure worth retrying.
+
+    Non-HTTP errors (e.g. connection/timeout) are treated as transient.
+    """
+    status_code = getattr(getattr(ex, "response", None), "status_code", None)
+    if status_code is None:
+        return True
+    return status_code in TRANSIENT_STATUS_CODES
+
+
+def retry_after_delay(ex: Exception) -> Optional[int]:
+    """Return the server-requested retry delay for throttling errors.
+
+    Reads the ``Retry-After`` header of a 429/503 response; returns ``None``
+    when it is unavailable or malformed so callers fall back to the backoff.
+
+    Args:
+        ex: The exception that was raised
+    """
+    response = getattr(ex, "response", None)
+    if response is None or getattr(response, "status_code", None) not in {429, 503}:
+        return None
+    return response_retry_after(response)
+
+
+def response_retry_after(response: Any) -> Optional[int]:
+    """Parse the ``Retry-After`` header (seconds) from a response, if any.
+
+    Returns ``None`` when the header is absent or malformed.
+
+    Args:
+        response: A ``requests.Response`` (or object exposing ``.headers``)
+    """
+    if response is None:
+        return None
+    value = response.headers.get("Retry-After", None)
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def backoff_delay(attempt: int, base: int, max_delay: Optional[int] = None, jitter: bool = True) -> float:
+    """Compute the delay before retry ``attempt``.
+
+    Exponential: ``base * 2 ** (attempt - 1)``, capped at ``max_delay``. With
+    ``jitter`` enabled (default) the delay is randomized in ``[0, delay]`` per
+    the "full jitter" strategy, avoiding synchronized retry storms.
+
+    Args:
+        attempt: 1-based retry attempt number.
+        base: Base delay in seconds (``timeout_secs``).
+        max_delay: Optional upper bound in seconds for the exponential growth.
+        jitter: Whether to randomize the delay (default True).
+
+    Returns:
+        Seconds to sleep before this attempt.
+    """
+    delay = base * (2 ** (attempt - 1))
+    if max_delay is not None:
+        delay = min(delay, max_delay)
+    if jitter:
+        delay = random.uniform(0, delay)
+    return delay
+
+
+def retry(
+    func: Callable[[], Any],
+    max_retry: int = 5,
+    timeout_secs: int = 5,
+    max_delay: Optional[int] = None,
+    jitter: bool = True,
+    exceptions: Tuple[Type[Exception], ...] = (ClientRequestException,),
+    is_retriable: Callable[[Exception], bool] = is_transient_error,
+    on_failure: Optional[Callable[[int, Exception], Optional[int]]] = None,
+    on_success: Optional[Callable[[Any], None]] = None,
+) -> Any:
+    """Run ``func``, retrying transient failures with exponential backoff.
+
+    Permanent failures re-raise immediately; the last exception is re-raised
+    once retries are exhausted.
+
+    The delay between attempts is exponential with jitter (``backoff_delay``);
+    when ``on_failure`` returns a delay (e.g. the server's ``Retry-After`` via
+    :func:`retry_after_delay`) that value overrides the backoff.
+
+    Args:
+        func: Callable to execute
+        max_retry: Maximum number of retry attempts
+        timeout_secs: Base delay for exponential backoff (seconds)
+        max_delay: Optional cap on the exponential delay (seconds)
+        jitter: Whether to randomize the delay (default True)
+        exceptions: Exception types that are candidates for retry
+        is_retriable: Classifier deciding whether a caught exception is retried
+        on_failure: Called after each failed attempt with ``(attempt, ex)``;
+            may return a retry delay (seconds) to override the backoff
+        on_success: Called with ``func()`` result on success
+    """
+    last_ex: Exception | None = None
+    for attempt in range(1, max_retry + 1):
+        try:
+            result = func()
+            if callable(on_success):
+                on_success(result)
+            return result
+        except exceptions as e:
+            if not callable(is_retriable) or not is_retriable(e):
+                raise
+            last_ex = e
+            retry_after: Optional[int] = None
+            if callable(on_failure):
+                retry_after = on_failure(attempt, e)
+            delay = retry_after if retry_after is not None else backoff_delay(attempt, timeout_secs, max_delay, jitter)
+            sleep(delay)
+    assert last_ex is not None
+    raise last_ex

office365/runtime/types/binary_content.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from office365.runtime.client_value import ClientValue
+
+
+@dataclass
+class BinaryContent(ClientValue):
+    data: bytes | None = None
+
+    @property
+    def entity_type_name(self) -> str:
+        return "microsoft.graph.BinaryContent"

office365/runtime/types/ipv4_cidr_range.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from office365.runtime.client_value import ClientValue
+
+
+@dataclass
+class IPv4CidrRange(ClientValue):
+    cidrAddress: str | None = None
+
+    @property
+    def entity_type_name(self) -> str:
+        return "microsoft.graph.IPv4CidrRange"

office365/runtime/types/ipv6_cidr_range.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from office365.runtime.client_value import ClientValue
+
+
+@dataclass
+class IPv6CidrRange(ClientValue):
+    cidrAddress: str | None = None
+
+    @property
+    def entity_type_name(self) -> str:
+        return "microsoft.graph.IPv6CidrRange"

office365/runtime/types/json.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from office365.runtime.client_value import ClientValue
+
+
+@dataclass
+class Json(ClientValue):
+    pass

office365/runtime/types/odata_property.py

@@ -7,7 +7,14 @@ _ODATA_MARKER = "__odata__"
 
 @dataclass
 class ODataPropertyMeta:
+    """Metadata for an ``@odata``-declared property.
+
+    ``name`` is the JSON/OData key; ``attr`` is the Python attribute name,
+    filled in by ``ClientObject.__init_subclass__`` at class creation.
+    """
+
     name: str
+    attr: str = ""
     persist: bool = False
     filterable: bool = False
     nullable: bool = True