bitwarden-py 0.1.0__tar.gz

bitwarden_py-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: bitwarden-py
+Version: 0.1.0
+Summary: A simple Python wrapper for the Bitwarden CLI — programmatically read and update passwords stored in your Bitwarden vault.
+Keywords: bitwarden,bitwarden-cli
+Author: SpaceShaman
+Author-email: SpaceShaman <spaceshaman@tuta.io>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Python: >=3.12
+Project-URL: Documentation, https://github.com/SpaceShaman/bitwarden-py
+Project-URL: Homepage, https://github.com/SpaceShaman/bitwarden-py
+Project-URL: Repository, https://github.com/SpaceShaman/bitwarden-py
+Description-Content-Type: text/markdown
+
+# bitwarden-py
+
+> A simple Python wrapper for the [Bitwarden CLI](https://bitwarden.com/help/cli/) — programmatically read and update passwords stored in your Bitwarden vault.
+
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/bitwarden-py)](https://pypi.org/project/bitwarden-py)
+[![PyPI - Version](https://img.shields.io/pypi/v/bitwarden-py)](https://pypi.org/project/bitwarden-py)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-black)](https://github.com/psf/black)
+[![Linting: Ruff](https://img.shields.io/badge/linting-Ruff-black?logo=ruff&logoColor=black)](https://github.com/astral-sh/ruff)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![GitHub License](https://img.shields.io/github/license/SpaceShaman/bitwarden-py)](https://github.com/SpaceShaman/bitwarden-py?tab=MIT-1-ov-file)
+
+---
+
+## Requirements
+
+### Bitwarden CLI
+
+`bitwarden-py` calls the official `bw` binary under the hood, so you must have it installed and available in your `PATH`.
+
+Install it by following the official guide:  
+👉 [https://bitwarden.com/help/cli/#download-and-install](https://bitwarden.com/help/cli/#download-and-install)
+
+Quick install options:
+
+```bash
+# macOS (Homebrew)
+brew install bitwarden-cli
+
+# Windows (Chocolatey)
+choco install bitwarden-cli
+
+# npm (cross-platform)
+npm install -g @bitwarden/cli
+```
+
+After installation, verify it works:
+
+```bash
+bw --version
+```
+
+---
+
+## Installation
+
+```bash
+pip install bitwarden-py
+```
+
+Or with [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv add bitwarden-py
+```
+
+---
+
+## Quick Start
+
+```python
+from bitwarden_py import Bitwarden
+
+bw = Bitwarden(
+    email="your@email.com",
+    password="your_master_password",
+)
+
+# Fetch a password by item name
+db_password = bw.get_password("My Database")
+print(db_password)  # → "s3cr3t!"
+
+# Update the password of an item
+bw.set_password("My Database", "n3wp4ssw0rd")
+```
+
+### Using a self-hosted server
+
+By default the library points to `https://vault.bitwarden.eu`.  
+Pass `server_url` to connect to a different instance:
+
+```python
+bw = Bitwarden(
+    email="your@email.com",
+    password="your_master_password",
+    server_url="https://bitwarden.yourcompany.com",
+)
+```
+
+---
+
+## API Reference
+
+### `Bitwarden(email, password, server_url?)`
+
+Creates a new client and authenticates with the vault.
+
+| Parameter    | Type  | Default                          | Description                        |
+|--------------|-------|----------------------------------|------------------------------------|
+| `email`      | `str` | —                                | Your Bitwarden account email       |
+| `password`   | `str` | —                                | Your master password               |
+| `server_url` | `str` | `"https://vault.bitwarden.eu"`   | Bitwarden server URL               |
+
+### `bw.get_password(item_name) → str`
+
+Returns the password of the vault item matching `item_name`.
+
+### `bw.set_password(item_name, new_password) → None`
+
+Updates the password of the vault item matching `item_name`.
+
+---
+
+## License
+
+[MIT](LICENSE)

bitwarden_py-0.1.0/README.md

@@ -0,0 +1,115 @@
+# bitwarden-py
+
+> A simple Python wrapper for the [Bitwarden CLI](https://bitwarden.com/help/cli/) — programmatically read and update passwords stored in your Bitwarden vault.
+
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/bitwarden-py)](https://pypi.org/project/bitwarden-py)
+[![PyPI - Version](https://img.shields.io/pypi/v/bitwarden-py)](https://pypi.org/project/bitwarden-py)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-black)](https://github.com/psf/black)
+[![Linting: Ruff](https://img.shields.io/badge/linting-Ruff-black?logo=ruff&logoColor=black)](https://github.com/astral-sh/ruff)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![GitHub License](https://img.shields.io/github/license/SpaceShaman/bitwarden-py)](https://github.com/SpaceShaman/bitwarden-py?tab=MIT-1-ov-file)
+
+---
+
+## Requirements
+
+### Bitwarden CLI
+
+`bitwarden-py` calls the official `bw` binary under the hood, so you must have it installed and available in your `PATH`.
+
+Install it by following the official guide:  
+👉 [https://bitwarden.com/help/cli/#download-and-install](https://bitwarden.com/help/cli/#download-and-install)
+
+Quick install options:
+
+```bash
+# macOS (Homebrew)
+brew install bitwarden-cli
+
+# Windows (Chocolatey)
+choco install bitwarden-cli
+
+# npm (cross-platform)
+npm install -g @bitwarden/cli
+```
+
+After installation, verify it works:
+
+```bash
+bw --version
+```
+
+---
+
+## Installation
+
+```bash
+pip install bitwarden-py
+```
+
+Or with [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv add bitwarden-py
+```
+
+---
+
+## Quick Start
+
+```python
+from bitwarden_py import Bitwarden
+
+bw = Bitwarden(
+    email="your@email.com",
+    password="your_master_password",
+)
+
+# Fetch a password by item name
+db_password = bw.get_password("My Database")
+print(db_password)  # → "s3cr3t!"
+
+# Update the password of an item
+bw.set_password("My Database", "n3wp4ssw0rd")
+```
+
+### Using a self-hosted server
+
+By default the library points to `https://vault.bitwarden.eu`.  
+Pass `server_url` to connect to a different instance:
+
+```python
+bw = Bitwarden(
+    email="your@email.com",
+    password="your_master_password",
+    server_url="https://bitwarden.yourcompany.com",
+)
+```
+
+---
+
+## API Reference
+
+### `Bitwarden(email, password, server_url?)`
+
+Creates a new client and authenticates with the vault.
+
+| Parameter    | Type  | Default                          | Description                        |
+|--------------|-------|----------------------------------|------------------------------------|
+| `email`      | `str` | —                                | Your Bitwarden account email       |
+| `password`   | `str` | —                                | Your master password               |
+| `server_url` | `str` | `"https://vault.bitwarden.eu"`   | Bitwarden server URL               |
+
+### `bw.get_password(item_name) → str`
+
+Returns the password of the vault item matching `item_name`.
+
+### `bw.set_password(item_name, new_password) → None`
+
+Updates the password of the vault item matching `item_name`.
+
+---
+
+## License
+
+[MIT](LICENSE)

bitwarden_py-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "bitwarden-py"
+version = "0.1.0"
+description = "A simple Python wrapper for the Bitwarden CLI — programmatically read and update passwords stored in your Bitwarden vault."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "SpaceShaman", email = "spaceshaman@tuta.io" }]
+keywords = ["bitwarden", "bitwarden-cli"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
+]
+dependencies = []
+
+[project.urls]
+Documentation = "https://github.com/SpaceShaman/bitwarden-py"
+Homepage = "https://github.com/SpaceShaman/bitwarden-py"
+Repository = "https://github.com/SpaceShaman/bitwarden-py"
+
+[build-system]
+requires = ["uv_build>=0.11.14,<0.12.0"]
+build-backend = "uv_build"

bitwarden_py-0.1.0/src/bitwarden_py/__init__.py

@@ -0,0 +1,3 @@
+from .main import Bitwarden
+
+__all__ = ["Bitwarden"]

bitwarden_py-0.1.0/src/bitwarden_py/command_runner.py

@@ -0,0 +1,14 @@
+import subprocess
+
+
+def run_command(command: list[str]) -> str:
+    try:
+        return subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            check=True,
+            stdin=subprocess.DEVNULL,
+        ).stdout.strip()
+    except subprocess.CalledProcessError as e:
+        raise RuntimeError(e.stderr.strip()) from e

bitwarden_py-0.1.0/src/bitwarden_py/commands.py

@@ -0,0 +1,78 @@
+import base64
+import json
+import os
+from dataclasses import dataclass
+from typing import Literal
+
+from .command_runner import run_command
+
+
+@dataclass
+class Status:
+    status: Literal["locked", "unlocked", "unauthenticated"]
+    server_url: str
+
+
+def get_status() -> Status:
+    output = run_command(["bw", "status"])
+    status_data = json.loads(output)
+    return Status(
+        status=status_data.get("status", "unauthenticated"),
+        server_url=status_data.get("serverUrl", ""),
+    )
+
+
+def login(email: str, password: str) -> None:
+    run_command(
+        [
+            "bw",
+            "login",
+            email,
+            password,
+            "--raw",
+        ],
+    )
+
+
+def logout() -> None:
+    run_command(["bw", "logout"])
+
+
+def set_server_url(url: str) -> None:
+    run_command(["bw", "config", "server", url])
+
+
+def get_session(password: str) -> str:
+    os.environ.setdefault("BW_PASSWORD", password)
+    return run_command(["bw", "unlock", "--raw", "--passwordenv", "BW_PASSWORD"])
+
+
+def get_password(session: str, item_name: str) -> str:
+    return run_command(["bw", "get", "password", item_name, "--session", session])
+
+
+def set_password(session: str, item_name: str, new_password: str) -> None:
+    item = json.loads(
+        run_command(["bw", "get", "item", item_name, "--session", session])
+    )
+
+    if not item.get("login"):
+        raise RuntimeError(f"Item '{item_name}' is not a login item")
+
+    item["login"]["password"] = new_password
+
+    encoded_item = base64.b64encode(
+        json.dumps(item, separators=(",", ":")).encode()
+    ).decode()
+
+    run_command(
+        [
+            "bw",
+            "edit",
+            "item",
+            item["id"],
+            encoded_item,
+            "--session",
+            session,
+        ]
+    )

bitwarden_py-0.1.0/src/bitwarden_py/main.py

@@ -0,0 +1,43 @@
+from .commands import (
+    get_password,
+    get_session,
+    get_status,
+    login,
+    logout,
+    set_password,
+    set_server_url,
+)
+
+
+class Bitwarden:
+    def __init__(
+        self,
+        email: str,
+        password: str,
+        server_url: str = "https://vault.bitwarden.eu",
+    ):
+        self._email = email
+        self._password = password
+        self._server_url = server_url
+        self._session = None
+        self._setup()
+
+    def _setup(self) -> None:
+        status = get_status()
+        if status.status != "unauthenticated":
+            logout()
+        if status.server_url != self._server_url:
+            set_server_url(self._server_url)
+        status = get_status()
+        login(self._email, self._password)
+        self._session = get_session(self._password)
+
+    def get_password(self, item_name: str) -> str:
+        if not self._session:
+            raise RuntimeError("Bitwarden session is not established.")
+        return get_password(self._session, item_name)
+
+    def set_password(self, item_name: str, new_password: str) -> None:
+        if not self._session:
+            raise RuntimeError("Bitwarden session is not established.")
+        set_password(self._session, item_name, new_password)