gitstore 0.2.0__tar.gz → 0.2.2__tar.gz

{gitstore-0.2.0/src/gitstore.egg-info → gitstore-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitstore
-Version: 0.2.0
+Version: 0.2.2
 Summary: Utilities to encrypt files/directories with utilitz and exchange them through GitHub repositories.
 Author: artitzco
 License: MIT
@@ -46,7 +46,7 @@ gitstore/
 ## Core API
 
 ```python
-from gitstore import upload_to_github, download_from_github
+from gitstore import upload_to_github, restore_from_github, restore_from_file
 ```
 
 ## Upload
@@ -106,10 +106,10 @@ folder/documento
 ## Download
 
 ```python
-from gitstore import download_from_github
+from gitstore import restore_from_github
 
-output_path = download_from_github(
-    github_url="https://github.com/USER/REPO/blob/main/vault/documento_ventas_q2.asc",
+output_path = restore_from_github(
+    github_raw_url="https://raw.githubusercontent.com/USER/REPO/main/vault/documento_ventas_q2.asc",
     password=None,      # default: uses GITSTORE_PASSWORD
     output_path=None,   # default: restores in the current working directory
     overwrite=False,    # default
@@ -118,18 +118,38 @@ output_path = download_from_github(
 print(output_path)
 ```
 
+Local restore (no network):
+
+```python
+from gitstore import restore_from_file
+
+output_path = restore_from_file(
+    encrypted_file_path="C:/downloads/documento_ventas_q2.asc",
+    password=None,      # default: uses GITSTORE_PASSWORD
+    output_path=None,   # optional
+    overwrite=False,    # default
+)
+print(output_path)
+```
+
+Tip:
+
+- use `restore_from_file(...)` when the target machine has SSL/certificate restrictions and you prefer manual transfer of the `.asc` file.
+
 Download behavior:
 
-- accepts normal GitHub file URLs (`github.com/.../blob/...`) and raw URLs
+- expects RAW GitHub URLs (`raw.githubusercontent.com/...`) as primary input
+- also accepts `github.com/.../blob/...` and normalizes automatically
 - skips download when `output_path` already exists and matches the remote `source_hash` in `vault/index.json`
 - set `force_download=True` to download even when the local output appears aligned
 - downloads the encrypted `.asc` file to a temporary location
 - restores files or directories automatically with `utilitz.crypto`
 - removes the temporary encrypted file after restore
+- supports local decode with `restore_from_file(...)` when manual download is preferred
 
 ## Password Source
 
-`upload_to_github` and `download_from_github` auto-detect password from:
+`upload_to_github`, `restore_from_github`, and `restore_from_file` auto-detect password from:
 
 - `GITSTORE_PASSWORD`
 

gitstore-0.2.0/PKG-INFO → gitstore-0.2.2/README.md

@@ -1,136 +1,145 @@
-Metadata-Version: 2.4
-Name: gitstore
-Version: 0.2.0
-Summary: Utilities to encrypt files/directories with utilitz and exchange them through GitHub repositories.
-Author: artitzco
-License: MIT
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-Requires-Dist: requests>=2.31.0
-Requires-Dist: utilitz[crypto]
-
-# gitstore
-
-`gitstore` is a focused Python package for one goal:
-
-- upload encrypted files/folders to a GitHub-backed repo
-- download and restore encrypted GitHub files later
-
-## Installation
-
-```bash
-pip install gitstore
-```
-
-## Dependency on `utilitz`
-
-This project depends on:
-
-- `utilitz[crypto]`
-- `requests`
-
-## Project Structure
-
-```text
-gitstore/
-  src/gitstore/
-    __init__.py
-    client.py
-    config.py
-    crypto_ops.py
-    github_ops.py
-  pyproject.toml
-  README.md
-```
-
-## Core API
-
-```python
-from gitstore import upload_to_github, download_from_github
-```
-
-## Upload
-
-```python
-from gitstore import upload_to_github
-
-record = upload_to_github(
-    source_path="C:/data/documento.pdf",  # file or directory
-    name="documento_ventas_q2",           # logical name only
-    repo_path="C:/repos/my-publish-repo", # required
-    password=None,                        # default: uses GITSTORE_PASSWORD
-    vault_dir="vault",                    # default
-    request_timeout=60,                   # default
-    security_level="high",                # default
-    replace_existing=True,                # default
-    force_upload=False,                   # default
-    commit_message=None,                  # default: automatic message
-)
-print(record)
-```
-
-Upload behavior:
-
-- computes `source_hash` from source content before encryption
-- skips upload if same `name` already has same `source_hash`
-- set `force_upload=True` to upload even when the current source matches the remote metadata
-- stores artifact as `vault/<name>.asc`
-- stores metadata in `vault/index.json`
-- removes temporary encrypted file after processing
-
-## Valid Names
-
-`name` is the logical identifier used to upload an artifact.
-It is intentionally strict to keep Git paths predictable:
-
-- allowed characters: letters, numbers, dots, underscores, and hyphens
-- must start with a letter or number
-- spaces and path separators are not allowed
-
-Valid examples:
-
-```text
-documento_ventas_q2
-maindb-version-0.1
-backup.2026_05
-```
-
-Invalid examples:
-
-```text
-maindb -version 0.1
-../secret
-folder/documento
-```
-
-## Download
-
-```python
-from gitstore import download_from_github
-
-output_path = download_from_github(
-    github_url="https://github.com/USER/REPO/blob/main/vault/documento_ventas_q2.asc",
-    password=None,      # default: uses GITSTORE_PASSWORD
-    output_path=None,   # default: restores in the current working directory
-    overwrite=False,    # default
-    force_download=False, # default
-)
-print(output_path)
-```
-
-Download behavior:
-
-- accepts normal GitHub file URLs (`github.com/.../blob/...`) and raw URLs
-- skips download when `output_path` already exists and matches the remote `source_hash` in `vault/index.json`
-- set `force_download=True` to download even when the local output appears aligned
-- downloads the encrypted `.asc` file to a temporary location
-- restores files or directories automatically with `utilitz.crypto`
-- removes the temporary encrypted file after restore
-
-## Password Source
-
-`upload_to_github` and `download_from_github` auto-detect password from:
-
-- `GITSTORE_PASSWORD`
-
-If `password` is not passed, the environment variable is used.
+# gitstore
+
+`gitstore` is a focused Python package for one goal:
+
+- upload encrypted files/folders to a GitHub-backed repo
+- download and restore encrypted GitHub files later
+
+## Installation
+
+```bash
+pip install gitstore
+```
+
+## Dependency on `utilitz`
+
+This project depends on:
+
+- `utilitz[crypto]`
+- `requests`
+
+## Project Structure
+
+```text
+gitstore/
+  src/gitstore/
+    __init__.py
+    client.py
+    config.py
+    crypto_ops.py
+    github_ops.py
+  pyproject.toml
+  README.md
+```
+
+## Core API
+
+```python
+from gitstore import upload_to_github, restore_from_github, restore_from_file
+```
+
+## Upload
+
+```python
+from gitstore import upload_to_github
+
+record = upload_to_github(
+    source_path="C:/data/documento.pdf",  # file or directory
+    name="documento_ventas_q2",           # logical name only
+    repo_path="C:/repos/my-publish-repo", # required
+    password=None,                        # default: uses GITSTORE_PASSWORD
+    vault_dir="vault",                    # default
+    request_timeout=60,                   # default
+    security_level="high",                # default
+    replace_existing=True,                # default
+    force_upload=False,                   # default
+    commit_message=None,                  # default: automatic message
+)
+print(record)
+```
+
+Upload behavior:
+
+- computes `source_hash` from source content before encryption
+- skips upload if same `name` already has same `source_hash`
+- set `force_upload=True` to upload even when the current source matches the remote metadata
+- stores artifact as `vault/<name>.asc`
+- stores metadata in `vault/index.json`
+- removes temporary encrypted file after processing
+
+## Valid Names
+
+`name` is the logical identifier used to upload an artifact.
+It is intentionally strict to keep Git paths predictable:
+
+- allowed characters: letters, numbers, dots, underscores, and hyphens
+- must start with a letter or number
+- spaces and path separators are not allowed
+
+Valid examples:
+
+```text
+documento_ventas_q2
+maindb-version-0.1
+backup.2026_05
+```
+
+Invalid examples:
+
+```text
+maindb -version 0.1
+../secret
+folder/documento
+```
+
+## Download
+
+```python
+from gitstore import restore_from_github
+
+output_path = restore_from_github(
+    github_raw_url="https://raw.githubusercontent.com/USER/REPO/main/vault/documento_ventas_q2.asc",
+    password=None,      # default: uses GITSTORE_PASSWORD
+    output_path=None,   # default: restores in the current working directory
+    overwrite=False,    # default
+    force_download=False, # default
+)
+print(output_path)
+```
+
+Local restore (no network):
+
+```python
+from gitstore import restore_from_file
+
+output_path = restore_from_file(
+    encrypted_file_path="C:/downloads/documento_ventas_q2.asc",
+    password=None,      # default: uses GITSTORE_PASSWORD
+    output_path=None,   # optional
+    overwrite=False,    # default
+)
+print(output_path)
+```
+
+Tip:
+
+- use `restore_from_file(...)` when the target machine has SSL/certificate restrictions and you prefer manual transfer of the `.asc` file.
+
+Download behavior:
+
+- expects RAW GitHub URLs (`raw.githubusercontent.com/...`) as primary input
+- also accepts `github.com/.../blob/...` and normalizes automatically
+- skips download when `output_path` already exists and matches the remote `source_hash` in `vault/index.json`
+- set `force_download=True` to download even when the local output appears aligned
+- downloads the encrypted `.asc` file to a temporary location
+- restores files or directories automatically with `utilitz.crypto`
+- removes the temporary encrypted file after restore
+- supports local decode with `restore_from_file(...)` when manual download is preferred
+
+## Password Source
+
+`upload_to_github`, `restore_from_github`, and `restore_from_file` auto-detect password from:
+
+- `GITSTORE_PASSWORD`
+
+If `password` is not passed, the environment variable is used.

{gitstore-0.2.0 → gitstore-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gitstore"
-version = "0.2.0"
+version = "0.2.2"
 description = "Utilities to encrypt files/directories with utilitz and exchange them through GitHub repositories."
 readme = "README.md"
 requires-python = ">=3.10"

{gitstore-0.2.0 → gitstore-0.2.2}/src/gitstore/__init__.py

@@ -1,13 +1,15 @@
 from .client import (
     DEFAULT_PASSWORD_ENV_VAR,
     StoredArtifact,
-    download_from_github,
+    restore_from_github,
+    restore_from_file,
     upload_to_github,
 )
 
 __all__ = [
     "StoredArtifact",
-    "download_from_github",
+    "restore_from_github",
+    "restore_from_file",
     "upload_to_github",
     "DEFAULT_PASSWORD_ENV_VAR",
 ]

{gitstore-0.2.0 → gitstore-0.2.2}/src/gitstore/client.py

@@ -96,8 +96,8 @@ def _hmac_source(path: Path, secret: str) -> str:
     return mac.hexdigest()
 
 
-def download_from_github(
-    github_url: str,
+def restore_from_github(
+    github_raw_url: str,
     password: str | None = None,
     output_path: str | None = None,
     overwrite: bool = False,
@@ -107,7 +107,7 @@ def download_from_github(
 ) -> str:
     resolved_password = _resolve_password(password, password_env_var)
     config = GitStoreConfig(password=resolved_password, request_timeout=request_timeout)
-    raw_url = normalize_github_file_url(github_url)
+    raw_url = normalize_github_file_url(github_raw_url)
     if output_path is not None and not overwrite and not force_download:
         existing_output = Path(output_path).expanduser().resolve()
         if existing_output.exists():
@@ -145,6 +145,28 @@ def download_from_github(
             shutil.rmtree(temp_dir, ignore_errors=True)
 
 
+def restore_from_file(
+    encrypted_file_path: str,
+    password: str | None = None,
+    output_path: str | None = None,
+    overwrite: bool = False,
+    password_env_var: str = DEFAULT_PASSWORD_ENV_VAR,
+) -> str:
+    resolved_password = _resolve_password(password, password_env_var)
+    config = GitStoreConfig(password=resolved_password, request_timeout=60)
+    encrypted_file = Path(encrypted_file_path).expanduser().resolve()
+    if not encrypted_file.is_file():
+        raise FileNotFoundError(f"Encrypted file not found: {encrypted_file}")
+    restored_path = decrypt_auto(
+        encrypted_path=str(encrypted_file),
+        config=config,
+        output_path=output_path,
+        overwrite=overwrite,
+    )
+    print(f"[gitstore] Restored local artifact '{encrypted_file}' -> '{restored_path}'.")
+    return restored_path
+
+
 def _load_remote_record_for_artifact(raw_url: str, request_timeout: int) -> dict:
     manifest_url = raw_url.rsplit("/", 1)[0] + "/index.json"
     artifact_name = raw_url.rsplit("/", 1)[-1]

gitstore-0.2.0/README.md → gitstore-0.2.2/src/gitstore.egg-info/PKG-INFO

@@ -1,125 +1,156 @@
-# gitstore
-
-`gitstore` is a focused Python package for one goal:
-
-- upload encrypted files/folders to a GitHub-backed repo
-- download and restore encrypted GitHub files later
-
-## Installation
-
-```bash
-pip install gitstore
-```
-
-## Dependency on `utilitz`
-
-This project depends on:
-
-- `utilitz[crypto]`
-- `requests`
-
-## Project Structure
-
-```text
-gitstore/
-  src/gitstore/
-    __init__.py
-    client.py
-    config.py
-    crypto_ops.py
-    github_ops.py
-  pyproject.toml
-  README.md
-```
-
-## Core API
-
-```python
-from gitstore import upload_to_github, download_from_github
-```
-
-## Upload
-
-```python
-from gitstore import upload_to_github
-
-record = upload_to_github(
-    source_path="C:/data/documento.pdf",  # file or directory
-    name="documento_ventas_q2",           # logical name only
-    repo_path="C:/repos/my-publish-repo", # required
-    password=None,                        # default: uses GITSTORE_PASSWORD
-    vault_dir="vault",                    # default
-    request_timeout=60,                   # default
-    security_level="high",                # default
-    replace_existing=True,                # default
-    force_upload=False,                   # default
-    commit_message=None,                  # default: automatic message
-)
-print(record)
-```
-
-Upload behavior:
-
-- computes `source_hash` from source content before encryption
-- skips upload if same `name` already has same `source_hash`
-- set `force_upload=True` to upload even when the current source matches the remote metadata
-- stores artifact as `vault/<name>.asc`
-- stores metadata in `vault/index.json`
-- removes temporary encrypted file after processing
-
-## Valid Names
-
-`name` is the logical identifier used to upload an artifact.
-It is intentionally strict to keep Git paths predictable:
-
-- allowed characters: letters, numbers, dots, underscores, and hyphens
-- must start with a letter or number
-- spaces and path separators are not allowed
-
-Valid examples:
-
-```text
-documento_ventas_q2
-maindb-version-0.1
-backup.2026_05
-```
-
-Invalid examples:
-
-```text
-maindb -version 0.1
-../secret
-folder/documento
-```
-
-## Download
-
-```python
-from gitstore import download_from_github
-
-output_path = download_from_github(
-    github_url="https://github.com/USER/REPO/blob/main/vault/documento_ventas_q2.asc",
-    password=None,      # default: uses GITSTORE_PASSWORD
-    output_path=None,   # default: restores in the current working directory
-    overwrite=False,    # default
-    force_download=False, # default
-)
-print(output_path)
-```
-
-Download behavior:
-
-- accepts normal GitHub file URLs (`github.com/.../blob/...`) and raw URLs
-- skips download when `output_path` already exists and matches the remote `source_hash` in `vault/index.json`
-- set `force_download=True` to download even when the local output appears aligned
-- downloads the encrypted `.asc` file to a temporary location
-- restores files or directories automatically with `utilitz.crypto`
-- removes the temporary encrypted file after restore
-
-## Password Source
-
-`upload_to_github` and `download_from_github` auto-detect password from:
-
-- `GITSTORE_PASSWORD`
-
-If `password` is not passed, the environment variable is used.
+Metadata-Version: 2.4
+Name: gitstore
+Version: 0.2.2
+Summary: Utilities to encrypt files/directories with utilitz and exchange them through GitHub repositories.
+Author: artitzco
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Requires-Dist: utilitz[crypto]
+
+# gitstore
+
+`gitstore` is a focused Python package for one goal:
+
+- upload encrypted files/folders to a GitHub-backed repo
+- download and restore encrypted GitHub files later
+
+## Installation
+
+```bash
+pip install gitstore
+```
+
+## Dependency on `utilitz`
+
+This project depends on:
+
+- `utilitz[crypto]`
+- `requests`
+
+## Project Structure
+
+```text
+gitstore/
+  src/gitstore/
+    __init__.py
+    client.py
+    config.py
+    crypto_ops.py
+    github_ops.py
+  pyproject.toml
+  README.md
+```
+
+## Core API
+
+```python
+from gitstore import upload_to_github, restore_from_github, restore_from_file
+```
+
+## Upload
+
+```python
+from gitstore import upload_to_github
+
+record = upload_to_github(
+    source_path="C:/data/documento.pdf",  # file or directory
+    name="documento_ventas_q2",           # logical name only
+    repo_path="C:/repos/my-publish-repo", # required
+    password=None,                        # default: uses GITSTORE_PASSWORD
+    vault_dir="vault",                    # default
+    request_timeout=60,                   # default
+    security_level="high",                # default
+    replace_existing=True,                # default
+    force_upload=False,                   # default
+    commit_message=None,                  # default: automatic message
+)
+print(record)
+```
+
+Upload behavior:
+
+- computes `source_hash` from source content before encryption
+- skips upload if same `name` already has same `source_hash`
+- set `force_upload=True` to upload even when the current source matches the remote metadata
+- stores artifact as `vault/<name>.asc`
+- stores metadata in `vault/index.json`
+- removes temporary encrypted file after processing
+
+## Valid Names
+
+`name` is the logical identifier used to upload an artifact.
+It is intentionally strict to keep Git paths predictable:
+
+- allowed characters: letters, numbers, dots, underscores, and hyphens
+- must start with a letter or number
+- spaces and path separators are not allowed
+
+Valid examples:
+
+```text
+documento_ventas_q2
+maindb-version-0.1
+backup.2026_05
+```
+
+Invalid examples:
+
+```text
+maindb -version 0.1
+../secret
+folder/documento
+```
+
+## Download
+
+```python
+from gitstore import restore_from_github
+
+output_path = restore_from_github(
+    github_raw_url="https://raw.githubusercontent.com/USER/REPO/main/vault/documento_ventas_q2.asc",
+    password=None,      # default: uses GITSTORE_PASSWORD
+    output_path=None,   # default: restores in the current working directory
+    overwrite=False,    # default
+    force_download=False, # default
+)
+print(output_path)
+```
+
+Local restore (no network):
+
+```python
+from gitstore import restore_from_file
+
+output_path = restore_from_file(
+    encrypted_file_path="C:/downloads/documento_ventas_q2.asc",
+    password=None,      # default: uses GITSTORE_PASSWORD
+    output_path=None,   # optional
+    overwrite=False,    # default
+)
+print(output_path)
+```
+
+Tip:
+
+- use `restore_from_file(...)` when the target machine has SSL/certificate restrictions and you prefer manual transfer of the `.asc` file.
+
+Download behavior:
+
+- expects RAW GitHub URLs (`raw.githubusercontent.com/...`) as primary input
+- also accepts `github.com/.../blob/...` and normalizes automatically
+- skips download when `output_path` already exists and matches the remote `source_hash` in `vault/index.json`
+- set `force_download=True` to download even when the local output appears aligned
+- downloads the encrypted `.asc` file to a temporary location
+- restores files or directories automatically with `utilitz.crypto`
+- removes the temporary encrypted file after restore
+- supports local decode with `restore_from_file(...)` when manual download is preferred
+
+## Password Source
+
+`upload_to_github`, `restore_from_github`, and `restore_from_file` auto-detect password from:
+
+- `GITSTORE_PASSWORD`
+
+If `password` is not passed, the environment variable is used.