Set up docs

Author: malmeloo

anisette/__init__.py

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/Makefile

@@ -0,0 +1,44 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+import anisette
+
+project = "Anisette.py"
+release = anisette.__version__
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.duration",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.inheritance_diagram",
+    "autoapi.extension",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- AutoAPI Options ---------------------------------------------------------
+autoapi_dirs = ["../src/anisette/"]
+autoapi_add_toctree_entry = False
+autoapi_options = [
+    "members",
+    "undoc-members",
+    "show-inheritance",
+    "show-module-summary",
+    "special-members",
+    "imported-members",
+]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"
+html_static_path = ["_static"]

docs/conf.py

@@ -0,0 +1,16 @@
+# Anisette.py
+
+## Jump To
+
+[//]: # (This is hidden to prevent it from showing on the home page)
+```{toctree}
+:hidden:
+Home <self>
+```
+
+[//]: # (Show these with a maxdepth of 1)
+```{toctree}
+:maxdepth: 1
+API Reference <autoapi/anisette/index>
+genindex
+```

docs/index.md

@@ -14,11 +14,15 @@ dependencies = [
 
 [dependency-groups]
 dev = [
+    "furo>=2024.8.6",
+    "myst-parser>=3.0.1",
     "packaging>=24.2",
     "pre-commit>=4.1.0",
     "pyright>=1.1.392.post0",
     "pytest>=8.3.4",
     "ruff>=0.9.3",
+    "sphinx>=7.4.7",
+    "sphinx-autoapi>=3.6.0",
     "tomli>=2.2.1",
 ]
 
@@ -37,8 +41,6 @@ select = [
     "ALL",
 ]
 ignore = [
-    "ANN101", # annotations on `self`
-    "ANN102", # annotations on `cls`
     "FIX002", # resolving TODOs
 
     "ERA001", # commented out code
@@ -57,7 +59,16 @@ ignore = [
     "FIX",
 ]
 
+[tool.ruff.lint.per-file-ignores]
+"docs/*" = ["ALL"]
+"tests/*" = ["D", "T", "ANN", "INP", "SLF"]
+"scripts/*" = ["T201"]
+
 [tool.pytest.ini_options]
 pythonpath = [
   "."
 ]
+
+[build-system]
+requires = ["setuptools", "setuptools-scm"]
+build-backend = "setuptools.build_meta"

pyproject.toml

@@ -1,5 +1,7 @@
 #!/usr/bin/env python3
 
+"""Find supported python versions for this package."""
+
 import json
 from collections.abc import Generator
 from itertools import count

scripts/supported_py_versions.py

@@ -0,0 +1,10 @@
+"""Anisette provider in a Python package."""
+
+from importlib.metadata import version
+
+from ._device import AnisetteDeviceConfig
+from .anisette import Anisette
+
+__version__ = version("anisette")
+
+__all__ = ("Anisette", "AnisetteDeviceConfig")

src/anisette/__init__.py

@@ -0,0 +1,163 @@
+"""Anisette provider in a Python package."""
+
+from __future__ import annotations
+
+import base64
+import logging
+from contextlib import ExitStack
+from ctypes import c_ulonglong
+from typing import TYPE_CHECKING, Any, BinaryIO
+
+from typing_extensions import Self
+
+from ._ani_provider import AnisetteProvider
+from ._fs import FSCollection
+from ._library import LibraryStore
+from ._util import open_file
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from ._device import AnisetteDeviceConfig
+
+
+class Anisette:
+    """
+    The main Anisette provider class.
+
+    This is the main Anisette provider class, which provides the user-facing functionality of this package.
+    Each instance of :class:`Anisette` represents a single Anisette session.
+
+    This class should not be instantiated directly through its __init__ method.
+    Instead, you should use :meth:`Anisette.init` or :meth:`Anisette.load` depending on your use case.
+    """
+
+    def __init__(self, ani_provider: AnisetteProvider) -> None:
+        """
+        Init.
+
+        :meta private:
+        """
+        self._ani_provider = ani_provider
+
+        self._ds_id = c_ulonglong(-2).value
+
+    @classmethod
+    def init(
+        cls,
+        apk_file: BinaryIO | str | Path,
+        default_device_config: AnisetteDeviceConfig | None = None,
+    ) -> Self:
+        """
+        Initialize a new Anisette session.
+
+        :param apk_file:
+        :param default_device_config:
+        :return:
+        """
+        with open_file(apk_file, "rb") as apk:
+            library_store = LibraryStore.from_apk(apk)
+
+        fs_collection = FSCollection(libs=library_store)
+        ani_provider = AnisetteProvider(fs_collection, default_device_config)
+
+        return cls(ani_provider)
+
+    @classmethod
+    def load(cls, *files: BinaryIO | str | Path, default_device_config: AnisetteDeviceConfig | None = None) -> Self:
+        """
+        Load a previously-initialized Anisette session.
+
+        :param files: File objects or paths that together form the provider's virtual file system. These can be obtained
+        using the :meth:`Anisette.save_provisioning`, :meth:`Anisette.save_libs`
+        and/or :meth:`Anisette.save_all` methods.
+        :type files: BinaryIO, str, Path
+        :return: An instance of :class:`Anisette`.
+        :rtype: :class:`Anisette`
+        """
+        with ExitStack() as stack:
+            file_objs = [stack.enter_context(open_file(f, "rb")) for f in files]
+            ani_provider = AnisetteProvider.load(*file_objs, default_device_config=default_device_config)
+
+        return cls(ani_provider)
+
+    def save_provisioning(self, file: BinaryIO | str | Path) -> None:
+        """
+        Save provisioning data of this Anisette session to a file.
+
+        The size of this file is usually in the order of kilobytes.
+
+        Saving provisioning data is required if you want to re-use this session at a later time.
+
+        A session may be reconstructed from saved data using the :meth:`Anisette.load` method.
+
+        The advantage of using this method over :meth:`Anisette.save_all` is that it results in less overall disk usage
+        when saving many sessions, since library data can be saved separately and may be re-used across sessions.
+
+        :param file: The file or path to save provisioning data to.
+        :type file: BinaryIO, str, Path
+        """
+        with open_file(file, "wb+") as f:
+            self._ani_provider.save(f, exclude=["libs"])
+
+    def save_libs(self, file: BinaryIO | str | Path) -> None:
+        """
+        Save library data to a file.
+
+        The size of this file is usually in the order of megabytes.
+
+        Library data is session-agnostic and may be used in as many sessions as you wish.
+
+        The advantage of using this method over :meth:`Anisette.save_all` is that it results in less overall disk usage
+        when saving many sessions, since library data can be saved separately and may be re-used across sessions.
+
+        :param file: The file or path to save library data to.
+        :type file: BinaryIO, str, Path
+        """
+        with open_file(file, "wb+") as f:
+            self._ani_provider.save(f, include=["libs"])
+
+    def save_all(self, file: BinaryIO | str | Path) -> None:
+        """
+        Save a complete copy of this Anisette session to a file.
+
+        The size of this file is usually in the order of megabytes.
+
+        Saving session data is required if you want to re-use this session at a later time.
+
+        A session may be reconstructed from saved data using the :meth:`Anisette.load` method.
+
+        The advantage of using this method over :meth:`Anisette.save_provisioning` and :meth:`Anisette.save_libs`
+        is that it is easier to use, since all information to reconstruct the session is contained in a single file.
+
+        :param file: The file or path to save session data to.
+        :type file: BinaryIO, str, Path
+        """
+        with open_file(file, "wb+") as f:
+            self._ani_provider.save(f)
+
+    def provision(self) -> None:
+        """
+        Provision the virtual device, if it has not been provisioned yet.
+
+        In most cases it is not necessary to manually use this method, since :meth:`Anisette.get_data`
+        will call it implicitly.
+        """
+        if not self._ani_provider.adi.is_machine_provisioned(self._ds_id):
+            logging.info("Provisioning...")
+            self._ani_provider.provisioning_session.provision(self._ds_id)
+
+    def get_data(self) -> dict[str, Any]:  # FIXME: make TypedDict
+        """
+        Obtain Anisette headers for this session.
+
+        :return: Anisette headers that may be used for authentication purposes.
+        """
+        self.provision()
+        otp = self._ani_provider.adi.request_otp(self._ds_id)
+
+        # FIXME: return other fields as well
+        return {
+            "X-Apple-I-MD": base64.b64encode(bytes(otp.otp)).decode(),
+            "X-Apple-I-MD-M": base64.b64encode(bytes(otp.machine_id)).decode(),
+        }