mail-intake/mcp_docs/modules/mail_intake.credentials.pickle.json

{
  "module": "mail_intake.credentials.pickle",
  "content": {
    "path": "mail_intake.credentials.pickle",
    "docstring": "Local filesystem–based credential persistence for Mail Intake.\n\n---\n\n## Summary\n\nThis module provides a file-backed implementation of the\n``CredentialStore`` abstraction using Python's ``pickle`` module.\n\nThe pickle-based credential store is intended for local development,\nsingle-node deployments, and controlled environments where credentials\ndo not need to be shared across processes or machines.\n\nDue to the security and portability risks associated with pickle-based\nserialization, this implementation is not suitable for distributed or\nuntrusted environments.",
    "objects": {
      "pickle": {
        "name": "pickle",
        "kind": "alias",
        "path": "mail_intake.credentials.pickle.pickle",
        "signature": "<bound method Alias.signature of Alias('pickle', 'pickle')>",
        "docstring": null
      },
      "Optional": {
        "name": "Optional",
        "kind": "alias",
        "path": "mail_intake.credentials.pickle.Optional",
        "signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
        "docstring": null
      },
      "TypeVar": {
        "name": "TypeVar",
        "kind": "alias",
        "path": "mail_intake.credentials.pickle.TypeVar",
        "signature": "<bound method Alias.signature of Alias('TypeVar', 'typing.TypeVar')>",
        "docstring": null
      },
      "CredentialStore": {
        "name": "CredentialStore",
        "kind": "class",
        "path": "mail_intake.credentials.pickle.CredentialStore",
        "signature": "<bound method Alias.signature of Alias('CredentialStore', 'mail_intake.credentials.store.CredentialStore')>",
        "docstring": "Abstract base class defining a generic persistence interface for\nauthentication credentials.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from storage mechanics\n        - Keep implementation focused only on persistence\n        \n    **Constraints:**\n    \n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored\n            - The serialization format used to persist credentials\n            - The underlying storage backend or durability guarantees",
        "members": {
          "load": {
            "name": "load",
            "kind": "function",
            "path": "mail_intake.credentials.pickle.CredentialStore.load",
            "signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
            "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are available and\n        loadable; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return ``None`` when no credentials are present or when stored credentials cannot be successfully decoded or deserialized\n        - The store must not attempt to validate, refresh, or otherwise interpret the returned credentials"
          },
          "save": {
            "name": "save",
            "kind": "function",
            "path": "mail_intake.credentials.pickle.CredentialStore.save",
            "signature": "<bound method Alias.signature of Alias('save', 'mail_intake.credentials.store.CredentialStore.save')>",
            "docstring": "Persist credentials to the underlying storage backend.\n\nArgs:\n    credentials (T):\n        The credential object to persist.\n\nNotes:\n    **Lifecycle:**\n\n        - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n\n    **Responsibilities:**\n\n        - Ensuring durability appropriate to the deployment context\n        - Applying encryption or access controls where required\n        - Overwriting any previously stored credentials"
          },
          "clear": {
            "name": "clear",
            "kind": "function",
            "path": "mail_intake.credentials.pickle.CredentialStore.clear",
            "signature": "<bound method Alias.signature of Alias('clear', 'mail_intake.credentials.store.CredentialStore.clear')>",
            "docstring": "Remove any persisted credentials from the store.\n\nNotes:\n    **Lifecycle:**\n\n        - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n        - Must ensure that no stale authentication material remains accessible\n\n    **Guarantees:**\n\n        - Implementations should treat this operation as idempotent"
          }
        }
      },
      "T": {
        "name": "T",
        "kind": "attribute",
        "path": "mail_intake.credentials.pickle.T",
        "signature": null,
        "docstring": null
      },
      "PickleCredentialStore": {
        "name": "PickleCredentialStore",
        "kind": "class",
        "path": "mail_intake.credentials.pickle.PickleCredentialStore",
        "signature": "<bound method Class.signature of Class('PickleCredentialStore', 28, 108)>",
        "docstring": "Filesystem-backed credential store using pickle serialization.\n\nThis store persists credentials as a pickled object on the local\nfilesystem. It is a simple implementation intended primarily for\ndevelopment, testing, and single-process execution contexts.\n\nNotes:\n    **Guarantees:**\n\n        - Stores credentials on the local filesystem\n        - Uses pickle for serialization and deserialization\n        - Does not provide encryption, locking, or concurrency guarantees\n\n    **Constraints:**\n    \n        - Credential lifecycle management, validation, and refresh logic are explicitly out of scope for this class",
        "members": {
          "path": {
            "name": "path",
            "kind": "attribute",
            "path": "mail_intake.credentials.pickle.PickleCredentialStore.path",
            "signature": null,
            "docstring": null
          },
          "load": {
            "name": "load",
            "kind": "function",
            "path": "mail_intake.credentials.pickle.PickleCredentialStore.load",
            "signature": "<bound method Function.signature of Function('load', 59, 78)>",
            "docstring": "Load credentials from the local filesystem.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are present and\n        successfully deserialized; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - If the credential file does not exist or cannot be successfully deserialized, this method returns ``None``\n        - The store does not attempt to validate or interpret the returned credentials"
          },
          "save": {
            "name": "save",
            "kind": "function",
            "path": "mail_intake.credentials.pickle.PickleCredentialStore.save",
            "signature": "<bound method Function.signature of Function('save', 80, 94)>",
            "docstring": "Persist credentials to the local filesystem.\n\nArgs:\n    credentials (T):\n        The credential object to persist.\n\nNotes:\n    **Responsibilities:**\n\n        - Any previously stored credentials at the configured path are overwritten"
          },
          "clear": {
            "name": "clear",
            "kind": "function",
            "path": "mail_intake.credentials.pickle.PickleCredentialStore.clear",
            "signature": "<bound method Function.signature of Function('clear', 96, 108)>",
            "docstring": "Remove persisted credentials from the local filesystem.\n\nNotes:\n    **Lifecycle:**\n\n        - This method deletes the credential file if it exists and should be treated as an idempotent operation"
          }
        }
      }
    }
  }
}