rowan-python 3.1.16__py3-none-any.whl → 3.2.1__py3-none-any.whl

rowan/api_keys.py

@@ -10,23 +10,23 @@ APIKeyScope = Literal["read", "read_write", "read_write_delete"]
 
 
 class APIKey(BaseModel):
-    """
-    Rowan API key.
-
-    :ivar uuid: UUID of the API key.
-    :ivar name: Human-readable name of the API key.
-    :ivar created_at: When the key was created.
-    :ivar expires_at: When the key expires.
-    :ivar is_expired: Whether the key has expired.
-    :ivar is_revoked: Whether the key has been revoked.
-    :ivar scope: Permission scope ("read", "read_write", or "read_write_delete").
-    :ivar can_manage_api_keys: Whether this key can create/list/revoke other API keys.
-    :ivar budget: Maximum credits this key may spend. ``None`` means unlimited.
-    :ivar credits_used: Credits spent by this key so far.
-    :ivar scoped_project_uuid: If set, the key can only access this project.
-    :ivar created_by_key_uuid: UUID of the API key used to create this one (if any).
-    :ivar revoked_at: When the key was revoked, if applicable.
-    :ivar last_used_at: When the key was last used, if known.
+    """Rowan API key.
+
+    Attributes:
+        uuid: UUID of the API key
+        name: human-readable name of the API key
+        created_at: when the key was created
+        expires_at: when the key expires
+        is_expired: whether the key has expired
+        is_revoked: whether the key has been revoked
+        scope: permission scope ("read", "read_write", or "read_write_delete")
+        can_manage_api_keys: whether this key can create/list/revoke other API keys
+        budget: maximum credits this key may spend. `None` means unlimited
+        credits_used: credits spent by this key so far
+        scoped_project_uuid: project to which access is restricted
+        created_by_key_uuid: UUID of the API key used to create this one (if any)
+        revoked_at: when the key was revoked, if applicable
+        last_used_at: when the key was last used, if known
     """
 
     uuid: str
@@ -51,10 +51,10 @@ class APIKey(BaseModel):
         )
 
     def revoke(self) -> Self:
-        """
-        Revoke this API key.
+        """Revoke this API key.
 
-        :returns: Updated APIKey object.
+        Returns:
+            updated APIKey object
         """
         with api_client() as client:
             response = client.post(f"/api_key/{self.uuid}/revoke")
@@ -62,12 +62,16 @@ class APIKey(BaseModel):
             return type(self)(**response.json())
 
     def refresh(self, in_place: bool = True) -> Self:
-        """
-        Reload this key's metadata (e.g. ``credits_used``) from the server.
+        """Reload this key's metadata (e.g. `credits_used`) from the server.
+
+        Args:
+            in_place: update this instance in place rather than return a new instance
 
-        :param in_place: If True, update this instance in-place. If False, return new instance.
-        :returns: Updated APIKey object.
-        :raises ValueError: If this key is no longer present in the account's key list.
+        Returns:
+            updated APIKey object
+
+        Raises:
+            ValueError: this key is no longer present in the account's key list
         """
         matches = [key for key in list_api_keys(active=None) if key.uuid == self.uuid]
         if not matches:
@@ -84,14 +88,14 @@ class APIKey(BaseModel):
 
 
 class CreatedAPIKey(BaseModel):
-    """
-    Result of creating a new API key.
+    """Result of creating a new API key.
 
-    The plaintext ``key`` is only available at creation time — store it now,
+    The plaintext `key` is only available at creation time – store it now,
     it cannot be retrieved later.
 
-    :ivar key: Plaintext API key. Save this; it is only returned once.
-    :ivar api_key: Metadata for the newly-created key.
+    Attributes:
+        key: plaintext API key. Save this; it is only returned once
+        api_key: metadata for the newly-created key
     """
 
     key: str
@@ -105,20 +109,22 @@ def create_api_key(
     scoped_project_uuid: str | None = None,
     budget: float | None = None,
 ) -> CreatedAPIKey:
-    """
-    Create a new API key.
+    """Create a new API key.
 
     The caller must currently authenticate with an unscoped key that has
-    ``can_manage_api_keys`` permission.
-
-    :param name: Human-readable name for the key.
-    :param scope: Permission scope. One of "read", "read_write", "read_write_delete".
-    :param valid_days: Number of days until the key expires.
-    :param scoped_project_uuid: If provided, restrict the key to a single project.
-    :param budget: Maximum credits the key may spend. If not provided, the key has no
-        spending limit.
-    :returns: plaintext key together with its metadata; the plaintext key is
-        only returned once — store it immediately.
+    `can_manage_api_keys` permission.
+
+    Args:
+        name: human-readable name for the key
+        scope: permission scope. One of "read", "read_write", "read_write_delete"
+        valid_days: number of days until the key expires
+        scoped_project_uuid: project to which access is restricted
+        budget: maximum credits the key may spend. If not provided, the key has no
+            spending limit
+
+    Returns:
+        plaintext key together with its metadata; the plaintext key is
+        only returned once – store it immediately
     """
     plaintext_key = f"rowan-sk{uuid.uuid4()}"
     payload = {
@@ -143,12 +149,14 @@ def create_api_key(
 
 
 def list_api_keys(active: bool | None = True) -> list[APIKey]:
-    """
-    List API keys belonging to the current user.
+    """List API keys belonging to the current user.
+
+    Args:
+        active: filter by key validity: True for non-revoked, non-expired keys,
+            False for revoked or expired keys, or None for all keys
 
-    :param active: If True (default), only return non-revoked, non-expired keys.
-        If False, only return revoked or expired keys. If None, return all keys.
-    :returns: List of APIKey objects.
+    Returns:
+        matching API keys
     """
     params: dict[str, str] = {}
     if active is not None:
@@ -161,11 +169,13 @@ def list_api_keys(active: bool | None = True) -> list[APIKey]:
 
 
 def revoke_api_key(uuid: str) -> APIKey:
-    """
-    Revoke an API key by UUID.
+    """Revoke an API key by UUID.
 
-    :param uuid: UUID of the key to revoke.
-    :returns: Updated APIKey object.
+    Args:
+        uuid: UUID of the key to revoke
+
+    Returns:
+        updated APIKey object
     """
     with api_client() as client:
         response = client.post(f"/api_key/{uuid}/revoke")
@@ -174,16 +184,18 @@ def revoke_api_key(uuid: str) -> APIKey:
 
 
 def update_api_key_budget(uuid: str, budget: float | None) -> APIKey:
-    """
-    Update the spending budget of an API key.
+    """Update the spending budget of an API key.
 
     The caller must currently authenticate with an unscoped key that has
-    ``can_manage_api_keys`` permission.
+    `can_manage_api_keys` permission.
+
+    Args:
+        uuid: UUID of the key to update
+        budget: new maximum credits the key may spend. Pass `None` to remove
+            the spending limit
 
-    :param uuid: UUID of the key to update.
-    :param budget: New maximum credits the key may spend. Pass ``None`` to remove
-        the spending limit.
-    :returns: Updated APIKey object.
+    Returns:
+        updated APIKey object
     """
     with api_client() as client:
         response = client.patch(f"/api_key/{uuid}", json={"budget": budget})

rowan/calculation.py

@@ -16,15 +16,15 @@ def _parse_molecules(data: list[dict]) -> list[Molecule]:
 
 
 class Calculation(BaseModel):
-    """
-    Rowan calculation result.
-
-    :param uuid: UUID of the calculation.
-    :param name: Name of the calculation.
-    :param status: Status code of the calculation.
-    :param elapsed: Execution time in seconds.
-    :param engine: Compute engine used.
-    :param molecules: Molecules (geometries) from this calculation.
+    """Rowan calculation result.
+
+    Attributes:
+        uuid: UUID of the calculation
+        name: name of the calculation
+        status: status code of the calculation
+        elapsed: execution time in seconds
+        engine: compute engine used
+        molecules: molecules (geometries) from this calculation
     """
 
     uuid: str
@@ -57,11 +57,13 @@ class Calculation(BaseModel):
         return None
 
     def refresh(self, in_place: bool = True) -> Self:
-        """
-        Fetch the latest calculation data from the API.
+        """Fetch the latest calculation data from the API.
+
+        Args:
+            in_place: update this instance in place rather than return a new instance
 
-        :param in_place: If True, update this instance in-place. If False, return new instance.
-        :returns: Updated Calculation object.
+        Returns:
+            updated Calculation object
         """
         try:
             with api_client() as client:
@@ -92,13 +94,17 @@ class Calculation(BaseModel):
 
 
 def retrieve_calculation(uuid: str) -> Calculation:
-    """
-    Retrieve a calculation from the API by UUID.
+    """Retrieve a calculation from the API by UUID.
+
+    Args:
+        uuid: UUID of the calculation to retrieve
+
+    Returns:
+        calculation object with the fetched data
 
-    :param uuid: UUID of the calculation to retrieve.
-    :returns: Calculation object with the fetched data.
-    :raises requests.HTTPError: If the API request fails.
-    :raises TimeoutError: If the response times out.
+    Raises:
+        httpx.HTTPStatusError: API request fails
+        TimeoutError: response times out
     """
     try:
         with api_client() as client:

rowan/config.py

@@ -354,15 +354,15 @@ BASIS_SET_ATOMS: dict[str, set[int]] = {
 
 @dataclass(frozen=True, slots=True)
 class ConformerGeneratorSettings:
-    """
-    Constraints for a conformer generator.
-
-    :param disable_constraints: Geometry constraints not supported.
-    :param disable_open_shell: Only closed-shell molecules supported.
-    :param disable_ts: Transition state search not supported.
-    :param atoms_supported: Supported atomic numbers (None = all).
-    :param allowed_engines: Engines allowed for energy evaluation (None = all).
-    :param solvent_warning: Warn if generator solvent differs from final opt solvent.
+    """Constraints for a conformer generator.
+
+    Attributes:
+        disable_constraints: geometry constraints not supported
+        disable_open_shell: only closed-shell molecules supported
+        disable_ts: transition state search not supported
+        atoms_supported: supported atomic numbers (None = all)
+        allowed_engines: engines allowed for energy evaluation (None = all)
+        solvent_warning: warn if generator solvent differs from final opt solvent
     """
 
     disable_constraints: bool = False
@@ -400,16 +400,16 @@ CONFORMER_GENERATOR_SETTINGS: dict[str, ConformerGeneratorSettings] = {
 
 @dataclass(frozen=True, slots=True)
 class MDSettings:
-    """
-    Molecular dynamics parameter constraints.
-
-    :param TIMESTEP_MIN: Minimum timestep in femtoseconds.
-    :param TIMESTEP_MAX: Maximum timestep in femtoseconds.
-    :param MAX_SAVED_FRAMES: Maximum number of frames that can be saved.
-    :param NPT_REQUIRES_PERIODIC: NPT ensemble only valid for periodic systems.
-    :param QUASICLASSICAL_REQUIRES_FREQUENCIES: Quasiclassical init needs frequencies.
-    :param READ_REQUIRES_VELOCITIES: Read init needs velocities from previous job.
-    :param CONFINING_BLOCKED_FOR_PERIODIC: Confining constraints invalid for periodic.
+    """Molecular dynamics parameter constraints.
+
+    Attributes:
+        TIMESTEP_MIN: minimum timestep in femtoseconds
+        TIMESTEP_MAX: maximum timestep in femtoseconds
+        MAX_SAVED_FRAMES: maximum number of frames that can be saved
+        NPT_REQUIRES_PERIODIC: NPT ensemble only valid for periodic systems
+        QUASICLASSICAL_REQUIRES_FREQUENCIES: quasiclassical init needs frequencies
+        READ_REQUIRES_VELOCITIES: read init needs velocities from previous job
+        CONFINING_BLOCKED_FOR_PERIODIC: confining constraints invalid for periodic
     """
 
     TIMESTEP_MIN: float = 0.5  # fs
@@ -432,12 +432,12 @@ MD_SETTINGS = MDSettings()
 
 @dataclass(frozen=True, slots=True)
 class SolubilityMethodSettings:
-    """
-    Constraints for solubility prediction methods.
+    """Constraints for solubility prediction methods.
 
-    :param allowed_solvents: Solvents supported (None = all). Use SMILES format.
-    :param single_temperature_k: If set, only this temperature allowed.
-    :param temperature_range: If set, (min_k, max_k) range allowed.
+    Attributes:
+        allowed_solvents: solvents supported (None = all). Use SMILES format
+        single_temperature_k: only allowed temperature, when specified
+        temperature_range: allowed temperature range (min_k, max_k)
     """
 
     allowed_solvents: list[str] | None = None
@@ -463,13 +463,13 @@ SOLUBILITY_METHOD_SETTINGS: dict[str, SolubilityMethodSettings] = {
 
 @dataclass(frozen=True, slots=True)
 class MacroPKaSettings:
-    """
-    MacroPKa workflow parameter constraints.
+    """MacroPKa workflow parameter constraints.
 
-    :param PH_WARNING_MIN: pH values below this trigger accuracy warning.
-    :param PH_WARNING_MAX: pH values above this trigger accuracy warning.
-    :param CHARGE_MIN: Minimum allowed charge state.
-    :param CHARGE_MAX: Maximum allowed charge state.
+    Attributes:
+        PH_WARNING_MIN: pH values below this trigger accuracy warning
+        PH_WARNING_MAX: pH values above this trigger accuracy warning
+        CHARGE_MIN: minimum allowed charge state
+        CHARGE_MAX: maximum allowed charge state
     """
 
     PH_WARNING_MIN: float = 0.0
@@ -487,15 +487,15 @@ TAUTOMER_ATOMS_SUPPORTED = [1, 5, 6, 7, 8, 9, 14, 15, 16, 17, 33, 34, 35, 53]
 
 @dataclass(frozen=True, slots=True)
 class CofoldingModelSettings:
-    """
-    Constraints for protein cofolding models.
-
-    :param max_sequence_length: Maximum total sequence length.
-    :param supports_cyclic_peptides: Whether cyclic peptides are supported.
-    :param supports_potentials: Whether potentials can be used.
-    :param supports_ligand_binding_affinity: Whether binding affinity available.
-    :param ligand_max_atoms: Max atoms per ligand for binding affinity.
-    :param ligand_atoms_supported: Supported atoms for ligand binding.
+    """Constraints for protein cofolding models.
+
+    Attributes:
+        max_sequence_length: maximum total sequence length
+        supports_cyclic_peptides: whether cyclic peptides are supported
+        supports_potentials: whether potentials can be used
+        supports_ligand_binding_affinity: whether binding affinity available
+        ligand_max_atoms: max atoms per ligand for binding affinity
+        ligand_atoms_supported: supported atoms for ligand binding
     """
 
     max_sequence_length: int = 3000
@@ -548,15 +548,15 @@ COFOLDING_MODEL_SETTINGS: dict[str, CofoldingModelSettings] = {
 
 @dataclass(frozen=True, slots=True)
 class BinderDesignSettings:
-    """
-    Protein binder design parameter constraints.
-
-    :param MAX_SEQUENCE_LENGTH: Maximum total amino acids.
-    :param NUM_DESIGNS_MAX_FREE: Max designs for free tier.
-    :param NUM_DESIGNS_MAX_SUBSCRIBED: Max designs for subscribed users.
-    :param BUDGET_MUST_BE_LEQ_NUM_DESIGNS: budget cannot exceed num_designs.
-    :param REQUIRES_DESIGNABLE_REGIONS: At least one sequence must have digits.
-    :param REQUIRES_UNIQUE_CHAIN_IDS: All chain IDs must be unique.
+    """Protein binder design parameter constraints.
+
+    Attributes:
+        MAX_SEQUENCE_LENGTH: maximum total amino acids
+        NUM_DESIGNS_MAX_FREE: max designs for free tier
+        NUM_DESIGNS_MAX_SUBSCRIBED: max designs for subscribed users
+        BUDGET_MUST_BE_LEQ_NUM_DESIGNS: budget cannot exceed num_designs
+        REQUIRES_DESIGNABLE_REGIONS: at least one sequence must have digits
+        REQUIRES_UNIQUE_CHAIN_IDS: all chain IDs must be unique
     """
 
     MAX_SEQUENCE_LENGTH: int = 1500
@@ -580,8 +580,11 @@ DOCKING_CSEARCH_REQUIRES_OPTIMIZATION = True
 def get_engine_settings(engine: str) -> EngineSettings | None:
     """Look up settings for a compute engine.
 
-    :param engine: Engine identifier string.
-    :returns: Settings for the engine, or None if not found.
+    Args:
+        engine: engine identifier string
+
+    Returns:
+        settings for the engine, or None if not found
     """
     return ENGINE_SETTINGS.get(engine)
 
@@ -589,8 +592,11 @@ def get_engine_settings(engine: str) -> EngineSettings | None:
 def get_method_settings(method: str) -> MethodSettings | None:
     """Look up settings for a calculation method.
 
-    :param method: Method identifier string.
-    :returns: Settings for the method, or None if not found.
+    Args:
+        method: method identifier string
+
+    Returns:
+        settings for the method, or None if not found
     """
     return METHOD_SETTINGS.get(method)
 
@@ -598,8 +604,11 @@ def get_method_settings(method: str) -> MethodSettings | None:
 def get_engines_for_method(method: str) -> list[str]:
     """Find all engines that support a given method.
 
-    :param method: Method identifier string.
-    :returns: List of engine identifier strings that support the method.
+    Args:
+        method: method identifier string
+
+    Returns:
+        list of engine identifier strings that support the method
     """
     return [engine for engine, settings in ENGINE_SETTINGS.items() if method in settings.methods]
 
@@ -611,10 +620,13 @@ def get_combined_settings(
 
     Merges engine and method constraints to give the full picture of what's supported.
 
-    :param engine: Engine identifier string.
-    :param method: Method identifier string.
-    :param periodic: Whether periodic boundary conditions are used.
-    :returns: Merged MethodSettings, or None if the combination is not supported.
+    Args:
+        engine: engine identifier string
+        method: method identifier string
+        periodic: whether periodic boundary conditions are used
+
+    Returns:
+        merged MethodSettings, or None if the combination is not supported
     """
     engine_settings = ENGINE_SETTINGS.get(engine)
     if engine_settings is None or method not in engine_settings.methods:
@@ -650,8 +662,11 @@ def get_combined_settings(
 def get_conformer_generator_settings(generator: str) -> ConformerGeneratorSettings | None:
     """Look up settings for a conformer generator.
 
-    :param generator: Conformer generator identifier string.
-    :returns: Settings for the generator, or None if not found.
+    Args:
+        generator: conformer generator identifier string
+
+    Returns:
+        settings for the generator, or None if not found
     """
     return CONFORMER_GENERATOR_SETTINGS.get(generator)
 
@@ -659,8 +674,11 @@ def get_conformer_generator_settings(generator: str) -> ConformerGeneratorSettin
 def get_solubility_method_settings(method: str) -> SolubilityMethodSettings | None:
     """Look up settings for a solubility prediction method.
 
-    :param method: Solubility method identifier string.
-    :returns: Settings for the method, or None if not found.
+    Args:
+        method: solubility method identifier string
+
+    Returns:
+        settings for the method, or None if not found
     """
     return SOLUBILITY_METHOD_SETTINGS.get(method)
 
@@ -668,7 +686,10 @@ def get_solubility_method_settings(method: str) -> SolubilityMethodSettings | No
 def get_cofolding_model_settings(model: str) -> CofoldingModelSettings | None:
     """Look up settings for a protein cofolding model.
 
-    :param model: Cofolding model identifier string.
-    :returns: Settings for the model, or None if not found.
+    Args:
+        model: cofolding model identifier string
+
+    Returns:
+        settings for the model, or None if not found
     """
     return COFOLDING_MODEL_SETTINGS.get(model)