pymacos 1.0.0__tar.gz

pymacos-1.0.0/.flake8

@@ -0,0 +1,12 @@
+[flake8]
+
+max-line-length = 130
+# E203: whitespace before ':' (black-compatible — black puts spaces around the
+#       colon in slices like data[i : i + n], which conflicts with PEP 8).
+# E701: multiple statements on one line (colon) — used pervasively as a style choice.
+# W503: line break before binary operator (black-compatible).
+ignore = E203, E701, W503
+
+per-file-ignores =
+    # __init__.py files are allowed to have unused imports and lines-too-long.
+    */__init__.py:F401, E501

pymacos-1.0.0/.gitignore

@@ -0,0 +1,83 @@
+# Byte-compiled / cached
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Build / packaging
+build/
+.build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+*.whl
+*.tar.gz
+pip-log.txt
+pip-delete-this-directory.txt
+MANIFEST
+
+# Virtual environments
+venv/
+.venv/
+env/
+ENV/
+
+# Testing & coverage
+.pytest_cache/
+*.pytest_cache
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+.tox/
+.nox/
+.hypothesis/
+
+# Type checkers & linters
+.mypy_cache/
+.ruff_cache/
+.pyre/
+.pytype/
+
+# IDEs / editors
+.idea/
+.vscode/
+*.code-workspace
+*.sublime-*
+.spyderproject
+.spyproject
+
+# Editor swap / backup files
+*.swp
+*.swo
+*~
+.\#*
+\#*\#
+
+# OS-specific cruft
+.DS_Store
+.AppleDouble
+.LSOverride
+Thumbs.db
+Desktop.ini
+.directory
+
+# Toolchain / version pinning state
+.tool-versions
+.python-version
+
+# Local environment files (never commit secrets)
+.env
+.env.local
+.env.*.local
+
+# Logs / temporary
+*.log
+*.tmp
+
+# Sphinx / docs build output
+docs/_build/
+
+# Project-local
+.claude/

pymacos-1.0.0/.readthedocs.yaml

@@ -0,0 +1,19 @@
+# Read the Docs configuration file for Sphinx + MyST.
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .

pymacos-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing
+
+Bug reports, ideas and pull requests are welcome on
+[GitHub](https://github.com/JeanExtreme002/pymacos).
+
+## Setup
+
+```bash
+git clone https://github.com/JeanExtreme002/pymacos.git
+cd pymacos
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+The `Makefile` wraps every command below: run `make help` to list the targets,
+for example `make check` (lint, type check and tests) or `make docs`.
+
+## Tests
+
+```bash
+pytest                  # everything, including live tests on your Mac
+pytest -m "not live"    # unit tests only (these also run on Linux)
+```
+
+The live tests talk to the real system. They restore your clipboard and delete
+the Keychain items they create.
+
+## Lint and type check
+
+```bash
+flake8 macos tests
+mypy macos
+```
+
+## Documentation
+
+```bash
+pip install -r docs/requirements.txt
+python -m sphinx -W -b html docs docs/_build/html
+```
+
+Then open `docs/_build/html/index.html`.
+
+## Pull requests
+
+- Use [Conventional Commits](https://www.conventionalcommits.org) for the title
+  (`feat: ...`, `fix: ...`, `docs: ...`).
+- Add a test for every bug fix and new feature.
+- Keep the package dependency-free.

pymacos-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jean Loui Bernard Silva de Jesus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pymacos-1.0.0/Makefile

@@ -0,0 +1,158 @@
+# Makefile for the pymacos Python package
+
+# Variables
+# The import name (the PyPI distribution is "pymacos").
+PACKAGE_NAME = macos
+PYTHON = python3
+PIP = $(PYTHON) -m pip
+VENV_DIR = .venv
+TEST_DIR = tests
+DIST_DIR = dist
+DOCS_DIR = docs
+DOCS_BUILD_DIR = $(DOCS_DIR)/_build/html
+
+# Colors for output
+GREEN = \033[0;32m
+YELLOW = \033[0;33m
+NC = \033[0m # No Color
+
+# Default target
+.PHONY: help
+help:
+	@echo "$(GREEN)pymacos Python package Makefile$(NC)"
+	@echo ""
+	@echo "Setup:"
+	@echo "  $(YELLOW)venv$(NC)             - Create a virtual environment in $(VENV_DIR)"
+	@echo "  $(YELLOW)install$(NC)          - Install the package in development mode"
+	@echo "  $(YELLOW)install-dev$(NC)      - Install the package with development dependencies"
+	@echo "  $(YELLOW)install-docs$(NC)     - Install the dependencies to build the documentation"
+	@echo ""
+	@echo "Checks:"
+	@echo "  $(YELLOW)test$(NC)             - Run all tests, including live tests against this Mac"
+	@echo "  $(YELLOW)test-unit$(NC)        - Run only the unit tests (no live tests)"
+	@echo "  $(YELLOW)test-coverage$(NC)    - Run all tests with a coverage report"
+	@echo "  $(YELLOW)lint$(NC)             - Run the linter (flake8)"
+	@echo "  $(YELLOW)type-check$(NC)       - Run the type checker (mypy)"
+	@echo "  $(YELLOW)check$(NC)            - Run lint, type-check and test"
+	@echo ""
+	@echo "Documentation:"
+	@echo "  $(YELLOW)docs$(NC)             - Build the HTML documentation (output: $(DOCS_BUILD_DIR))"
+	@echo "  $(YELLOW)docs-serve$(NC)       - Live-reload docs server at http://127.0.0.1:8000"
+	@echo "  $(YELLOW)docs-clean$(NC)       - Remove the docs build directory"
+	@echo ""
+	@echo "Packaging:"
+	@echo "  $(YELLOW)build$(NC)            - Build the wheel and source distribution"
+	@echo "  $(YELLOW)validate$(NC)         - Build and check the distributions with twine"
+	@echo "  $(YELLOW)version$(NC)          - Show the current version"
+	@echo "  $(YELLOW)clean$(NC)            - Remove build, test and cache artifacts"
+
+# Create virtual environment
+.PHONY: venv
+venv:
+	@echo "$(GREEN)Creating virtual environment...$(NC)"
+	$(PYTHON) -m venv $(VENV_DIR)
+	@echo "$(YELLOW)To activate: source $(VENV_DIR)/bin/activate$(NC)"
+
+# Install package in development mode (it has no runtime dependencies)
+.PHONY: install
+install:
+	@echo "$(GREEN)Installing package in development mode...$(NC)"
+	$(PIP) install -e .
+
+# Install development dependencies (pytest, flake8, mypy, build, twine)
+.PHONY: install-dev
+install-dev:
+	@echo "$(GREEN)Installing development dependencies...$(NC)"
+	$(PIP) install -e ".[dev]"
+
+# Install the documentation dependencies, plus the package so autodoc can import it
+.PHONY: install-docs
+install-docs:
+	@echo "$(GREEN)Installing documentation dependencies...$(NC)"
+	$(PIP) install -r $(DOCS_DIR)/requirements.txt
+	$(PIP) install -e .
+
+# Run all tests. The live ones talk to the real system: they restore the
+# clipboard and delete the Keychain items they create.
+.PHONY: test
+test:
+	@echo "$(GREEN)Running tests...$(NC)"
+	$(PYTHON) -m pytest $(TEST_DIR) -v
+
+# Run only the unit tests, which don't touch the system (they also run on Linux)
+.PHONY: test-unit
+test-unit:
+	@echo "$(GREEN)Running unit tests...$(NC)"
+	$(PYTHON) -m pytest $(TEST_DIR) -v -m "not live"
+
+# Run tests with coverage
+.PHONY: test-coverage
+test-coverage:
+	@echo "$(GREEN)Running tests with coverage...$(NC)"
+	$(PYTHON) -m pytest $(TEST_DIR) --cov=$(PACKAGE_NAME) --cov-report=html --cov-report=term
+	@echo "$(YELLOW)HTML report available at htmlcov/index.html$(NC)"
+
+# Run linter
+.PHONY: lint
+lint:
+	@echo "$(GREEN)Running linter (flake8)...$(NC)"
+	$(PYTHON) -m flake8 $(PACKAGE_NAME) $(TEST_DIR)
+
+# Run type checker (config in pyproject.toml)
+.PHONY: type-check
+type-check:
+	@echo "$(GREEN)Running type checker (mypy)...$(NC)"
+	$(PYTHON) -m mypy $(PACKAGE_NAME)
+
+# Everything CI runs on a pull request, except the docs build
+.PHONY: check
+check: lint type-check test
+	@echo "$(GREEN)All checks passed!$(NC)"
+
+# Build the HTML documentation with the same flags as CI and Read the Docs:
+# warnings, including broken cross-references (-n), fail the build.
+.PHONY: docs
+docs:
+	@echo "$(GREEN)Building HTML documentation...$(NC)"
+	$(PYTHON) -m sphinx -n -W --keep-going -b html $(DOCS_DIR) $(DOCS_BUILD_DIR)
+	@echo "$(GREEN)Documentation generated at $(DOCS_BUILD_DIR)/index.html$(NC)"
+
+# Live-reload docs server. sphinx-autobuild is installed on demand. After
+# changing a toctree, restart it: it only rebuilds changed pages, so the
+# sidebar on the other pages goes stale.
+.PHONY: docs-serve
+docs-serve:
+	@echo "$(GREEN)Starting live-reload docs server at http://127.0.0.1:8000$(NC)"
+	@$(PYTHON) -c "import sphinx_autobuild" 2>/dev/null || $(PIP) install sphinx-autobuild
+	$(PYTHON) -m sphinx_autobuild $(DOCS_DIR) $(DOCS_BUILD_DIR) --open-browser
+
+# Wipe the built docs
+.PHONY: docs-clean
+docs-clean:
+	@echo "$(GREEN)Cleaning docs build directory...$(NC)"
+	rm -rf $(DOCS_DIR)/_build
+
+# Build package. Releases are published by the GitHub workflow when a
+# release is created, so there is no publish target here.
+.PHONY: build
+build: clean
+	@echo "$(GREEN)Building package...$(NC)"
+	$(PYTHON) -m build
+
+# Validate package
+.PHONY: validate
+validate: build
+	@echo "$(GREEN)Validating package...$(NC)"
+	$(PYTHON) -m twine check $(DIST_DIR)/*
+
+# Show current version
+.PHONY: version
+version:
+	@$(PYTHON) -c "import $(PACKAGE_NAME); print($(PACKAGE_NAME).__version__)"
+
+# Clean build artifacts
+.PHONY: clean
+clean:
+	@echo "$(GREEN)Cleaning build artifacts...$(NC)"
+	rm -rf build $(DIST_DIR) *.egg-info .pytest_cache .mypy_cache htmlcov .coverage coverage.xml
+	find . -path ./$(VENV_DIR) -prune -o -type d -name "__pycache__" -exec rm -rf {} +

pymacos-1.0.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.5
+Name: pymacos
+Version: 1.0.0
+Summary: A Pythonic interface to macOS — notifications, clipboard, dark mode, apps, Keychain, speech and screenshots in one dependency-free import.
+Project-URL: Homepage, https://github.com/JeanExtreme002/pymacos
+Project-URL: Documentation, https://macos.readthedocs.io
+Project-URL: Repository, https://github.com/JeanExtreme002/pymacos
+Project-URL: Issues, https://github.com/JeanExtreme002/pymacos/issues
+Project-URL: Changelog, https://github.com/JeanExtreme002/pymacos/releases
+Project-URL: Funding, https://github.com/sponsors/JeanExtreme002
+Author-email: Jean Loui Bernard Silva de Jesus <contact@jeanloui.dev>
+Maintainer-email: Jean Loui Bernard Silva de Jesus <contact@jeanloui.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: appkit,automation,clipboard,cocoa,ctypes,dark-mode,keychain,mac,macos,notifications,osx,screenshot,text-to-speech
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Desktop Environment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: flake8; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pymacos
+
+**A Pythonic interface to macOS.** Notifications, clipboard, dark mode, apps, Keychain, speech and screenshots, all from one import with zero dependencies.
+
+```python
+import macos
+
+macos.notify("Build finished", title="CI")
+macos.clipboard.copy("hello")
+macos.appearance.is_dark()                 # True
+macos.apps.open("Safari")                  # App(name='Safari', ...)
+macos.keychain.get("my-app", "alice")      # 's3cret'
+macos.say("Done!")
+macos.screenshot("screen.png")
+```
+
+## Install
+
+```bash
+pip install pymacos
+```
+
+The package is installed as `pymacos` and imported as `macos`.
+
+Requires macOS and Python 3.9+.
+
+## Why
+
+Doing any of this from Python usually means shelling out to `osascript`, remembering `defaults` keys, or pulling in PyObjC and learning Cocoa. `pymacos` gives you one small, typed API instead:
+
+- **No dependencies.** Native features call the system frameworks through `ctypes`; the rest wraps tools that ship with every Mac.
+- **Pythonic.** Plain functions, dataclasses and real exceptions, not Objective-C selectors or exit codes.
+- **Safe by default.** Your text is never spliced into shell or AppleScript source, and passwords never show up in the process list.
+- **Helpful errors.** A missing privacy permission raises an error that says where to enable it, instead of failing silently.
+
+## Documentation
+
+The full guide and API reference are at **[macos.readthedocs.io](https://macos.readthedocs.io)**.
+
+## License
+
+Released under the [MIT License](https://github.com/JeanExtreme002/pymacos/blob/main/LICENSE) — free for personal and commercial use.
+
+<sub>Not affiliated with or endorsed by Apple Inc. macOS is a trademark of Apple Inc.</sub>

pymacos-1.0.0/README.md

@@ -0,0 +1,44 @@
+# pymacos
+
+**A Pythonic interface to macOS.** Notifications, clipboard, dark mode, apps, Keychain, speech and screenshots, all from one import with zero dependencies.
+
+```python
+import macos
+
+macos.notify("Build finished", title="CI")
+macos.clipboard.copy("hello")
+macos.appearance.is_dark()                 # True
+macos.apps.open("Safari")                  # App(name='Safari', ...)
+macos.keychain.get("my-app", "alice")      # 's3cret'
+macos.say("Done!")
+macos.screenshot("screen.png")
+```
+
+## Install
+
+```bash
+pip install pymacos
+```
+
+The package is installed as `pymacos` and imported as `macos`.
+
+Requires macOS and Python 3.9+.
+
+## Why
+
+Doing any of this from Python usually means shelling out to `osascript`, remembering `defaults` keys, or pulling in PyObjC and learning Cocoa. `pymacos` gives you one small, typed API instead:
+
+- **No dependencies.** Native features call the system frameworks through `ctypes`; the rest wraps tools that ship with every Mac.
+- **Pythonic.** Plain functions, dataclasses and real exceptions, not Objective-C selectors or exit codes.
+- **Safe by default.** Your text is never spliced into shell or AppleScript source, and passwords never show up in the process list.
+- **Helpful errors.** A missing privacy permission raises an error that says where to enable it, instead of failing silently.
+
+## Documentation
+
+The full guide and API reference are at **[macos.readthedocs.io](https://macos.readthedocs.io)**.
+
+## License
+
+Released under the [MIT License](https://github.com/JeanExtreme002/pymacos/blob/main/LICENSE) — free for personal and commercial use.
+
+<sub>Not affiliated with or endorsed by Apple Inc. macOS is a trademark of Apple Inc.</sub>

pymacos-1.0.0/docs/_static/custom.css

@@ -0,0 +1,68 @@
+/* pymacos docs: tweaks on top of the Read the Docs theme. */
+
+/* --- Repository link (injected in _templates/layout.html) --------------- */
+/* A quiet card at the top of the sidebar: GitHub icon, repo name and live
+   star/fork counts. Scoped under `.wy-menu-vertical a` so it beats the RTD
+   theme's own `.wy-menu-vertical a { display: block; ... }` rule. */
+.wy-menu-vertical a.repo-link {
+  display: flex;
+  align-items: center;
+  gap: 0.65rem;
+  margin: 0.6rem 0.8rem 0.4rem;
+  padding: 0.55rem 0.7rem;
+  border-radius: 0.35rem;
+  color: #d9d9d9;
+  line-height: 1.25;
+  text-decoration: none;
+  transition: background 0.15s ease, color 0.15s ease;
+}
+
+.wy-menu-vertical a.repo-link:hover,
+.wy-menu-vertical a.repo-link:focus-visible {
+  background: rgba(255, 255, 255, 0.08);
+  color: #fff;
+}
+
+.repo-link__icon {
+  flex-shrink: 0;
+}
+
+.repo-link__text {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+
+.repo-link__name {
+  overflow: hidden;
+  font-size: 0.8rem;
+  font-weight: 600;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.repo-link__stats {
+  display: flex;
+  gap: 0.75rem;
+  margin-top: 0.15rem;
+  font-size: 0.72rem;
+  opacity: 0.75;
+}
+
+.repo-link__stats[hidden] {
+  display: none;
+}
+
+.repo-link__stat {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+}
+
+/* The RTD theme's JavaScript injects a `<button class="toctree-expand">` as the
+   first child of every link inside `.wy-menu-vertical` (the expand/collapse
+   caret for nav items with children). The repo link isn't a nav item, so that
+   button would render as a stray white pill: hide it. */
+.repo-link button.toctree-expand {
+  display: none;
+}

pymacos-1.0.0/docs/_templates/layout.html

@@ -0,0 +1,60 @@
+{#- Extend the Read the Docs theme with a link to the GitHub repository at the
+    top of the sidebar, on every page: the repo name plus its live star and fork
+    counts, instead of a "please star" button. The counts come from the public
+    GitHub API; if that fails (offline, rate limit) only the name is shown. -#}
+{% extends "!layout.html" %}
+
+{% block menu %}
+  <a class="repo-link"
+     href="https://github.com/{{ github_user }}/{{ github_repo }}"
+     target="_blank" rel="noopener noreferrer"
+     title="Source code on GitHub">
+    <svg class="repo-link__icon" aria-hidden="true" viewBox="0 0 16 16" width="22" height="22">
+      <path fill="currentColor" fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"></path>
+    </svg>
+    <span class="repo-link__text">
+      <span class="repo-link__name">{{ github_user }}/{{ github_repo }}</span>
+      <span class="repo-link__stats" hidden>
+        <span class="repo-link__stat" title="Stars">
+          <svg aria-hidden="true" viewBox="0 0 16 16" width="12" height="12"><path fill="currentColor" d="M8 .25a.75.75 0 0 1 .673.418l1.882 3.815 4.21.612a.75.75 0 0 1 .416 1.279l-3.046 2.97.719 4.192a.751.751 0 0 1-1.088.791L8 12.347l-3.766 1.98a.75.75 0 0 1-1.088-.79l.72-4.194L.818 6.374a.75.75 0 0 1 .416-1.28l4.21-.611L7.327.668A.75.75 0 0 1 8 .25Z"></path></svg>
+          <span data-repo-stars></span>
+        </span>
+        <span class="repo-link__stat" title="Forks">
+          <svg aria-hidden="true" viewBox="0 0 16 16" width="12" height="12"><path fill="currentColor" d="M5 5.372v.878c0 .414.336.75.75.75h4.5a.75.75 0 0 0 .75-.75v-.878a2.25 2.25 0 1 1 1.5 0v.878a2.25 2.25 0 0 1-2.25 2.25h-1.5v2.128a2.251 2.251 0 1 1-1.5 0V8.5h-1.5A2.25 2.25 0 0 1 3.5 6.25v-.878a2.25 2.25 0 1 1 1.5 0ZM5 3.25a.75.75 0 1 0-1.5 0 .75.75 0 0 0 1.5 0Zm6.75.75a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5Zm-3 8.75a.75.75 0 1 0-1.5 0 .75.75 0 0 0 1.5 0Z"></path></svg>
+          <span data-repo-forks></span>
+        </span>
+      </span>
+    </span>
+  </a>
+  <script>
+    (function () {
+      var repo = "{{ github_user }}/{{ github_repo }}";
+      var key = "repo-stats:" + repo;
+
+      function show(data) {
+        var stats = document.querySelector(".repo-link__stats");
+        if (!stats || typeof data.stars !== "number") return;
+        stats.querySelector("[data-repo-stars]").textContent = data.stars.toLocaleString();
+        stats.querySelector("[data-repo-forks]").textContent = data.forks.toLocaleString();
+        stats.hidden = false;
+      }
+
+      // Cache per browser session: GitHub allows 60 unauthenticated requests
+      // an hour per IP, and every page view would otherwise spend one.
+      try {
+        var cached = sessionStorage.getItem(key);
+        if (cached) { show(JSON.parse(cached)); return; }
+      } catch (e) {}
+
+      fetch("https://api.github.com/repos/" + repo)
+        .then(function (response) { return response.ok ? response.json() : Promise.reject(); })
+        .then(function (json) {
+          var data = { stars: json.stargazers_count, forks: json.forks_count };
+          try { sessionStorage.setItem(key, JSON.stringify(data)); } catch (e) {}
+          show(data);
+        })
+        .catch(function () {});
+    })();
+  </script>
+  {{ super() }}
+{% endblock %}

pymacos-1.0.0/docs/api.md

@@ -0,0 +1,85 @@
+# API
+
+The complete public API, generated from the source code. The feature pages
+explain how to use each part.
+
+## Top-level functions
+
+```{eval-rst}
+.. autofunction:: macos.notify
+.. autofunction:: macos.say
+.. autofunction:: macos.screenshot
+```
+
+## macos.clipboard
+
+```{eval-rst}
+.. module:: macos.clipboard
+
+.. autofunction:: macos.clipboard.copy
+.. autofunction:: macos.clipboard.paste
+.. autofunction:: macos.clipboard.clear
+.. autofunction:: macos.clipboard.change_count
+```
+
+## macos.appearance
+
+```{eval-rst}
+.. module:: macos.appearance
+
+.. autofunction:: macos.appearance.is_dark
+.. autofunction:: macos.appearance.mode
+.. autofunction:: macos.appearance.is_auto
+```
+
+## macos.apps
+
+```{eval-rst}
+.. module:: macos.apps
+
+.. autofunction:: macos.apps.running
+.. autofunction:: macos.apps.frontmost
+.. autofunction:: macos.apps.get
+.. autofunction:: macos.apps.open
+.. autoclass:: macos.apps.App
+   :members: is_running, is_active, is_hidden, activate, hide, unhide, quit
+```
+
+## macos.keychain
+
+```{eval-rst}
+.. module:: macos.keychain
+
+.. autofunction:: macos.keychain.set
+.. autofunction:: macos.keychain.get
+.. autofunction:: macos.keychain.delete
+```
+
+## macos.speech
+
+```{eval-rst}
+.. module:: macos.speech
+
+.. autofunction:: macos.speech.voices
+.. autoclass:: macos.speech.Voice
+```
+
+## macos.screen
+
+```{eval-rst}
+.. module:: macos.screen
+
+.. autofunction:: macos.screen.has_permission
+.. autofunction:: macos.screen.request_permission
+```
+
+## Exceptions
+
+```{eval-rst}
+.. autoexception:: macos.MacOSError
+.. autoexception:: macos.NotSupportedError
+.. autoexception:: macos.PermissionDeniedError
+.. autoexception:: macos.AppNotFoundError
+.. autoexception:: macos.KeychainError
+.. autoexception:: macos.CommandError
+```