s3v 0.1.0__tar.gz

s3v-0.1.0/.gitignore

@@ -0,0 +1,207 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

s3v-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yaroslav
+
+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.

s3v-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: s3v
+Version: 0.1.0
+Summary: Convenient CLI tool to work with versioned (including Object Lock) S3 buckets (recover, undelete, etc.)
+Project-URL: Homepage, https://github.com/yaroslaff/s3v
+Project-URL: Issues, https://github.com/yaroslaff/s3v/issues
+Author-email: Yaroslav Polyakov <yaroslaff@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Yaroslav
+        
+        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.
+License-File: LICENSE
+Keywords: aws,bucket,cli,object lock,recover,retention,s3,undelete,versioned
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Requires-Dist: boto3>=1.28.0
+Requires-Dist: botocore>=1.31.0
+Description-Content-Type: text/markdown
+
+# s3v
+Convinient CLI tool to work with versioned S3 buckets. Like `aws s3` or `aws s3api` but much easier to use.
+
+## Installation
+~~~
+# recommended
+pipx install s3v
+
+# or from git
+pipx install git+https://github.com/yaroslaff/s3v
+~~~
+
+## Configuration
+s3v uses boto3, so configuration is same as for `aws` utility (same `~/.aws/` files or `AWS_` shell variables, and optional `--profile NAME` argument)
+
+## Examples
+
+We upload three versions of same file, each one will overwrite old copy. In "ls" we see filename, last modification time, size of latest copy and number of versions in storage.
+
+### Upload
+
+```bash
+$ echo 1 > test.txt 
+$ s3v cp test.txt s3://stg-objectlock/s3v/
+$ echo 2 > test.txt 
+$ s3v cp test.txt s3://stg-objectlock/s3v/
+$ echo 3 > test.txt 
+$ s3v cp test.txt s3://stg-objectlock/s3v/
+```
+You can also give full target name like s3://stg-objectlock/s3v/test.txt. `s3://` prefix is optional ()
+
+
+### List
+Now, list contents of s3v logical 'folder' (all objects with name starting with `s3v/`). If we give full name of object, ls will list all versions.
+
+```bash
+$ s3v ls stg-objectlock/s3v
+Listing objects in bucket 'stg-objectlock' with prefix 's3v'
+test.txt                                |2026-02-10 16:21:55|              2|   3|
+
+$ s3v ls stg-objectlock/s3v/test.txt
+Listing objects in bucket 'stg-objectlock' with prefix 's3v/test.txt'
+Objects under prefix 's3v/test.txt':
+s3v/test.txt
+   by0fQCa9Jl7gFgl8vKEjaDvl8z3CSRnD          2  2026-02-10 16:21:30
+   LHK6nA8Ny5YHNh7TOoH94LDinqCH9Czt          2  2026-02-10 16:21:46
+   iIGXCsBmEKvBq7DhaP09DIzp3fLO9d1H          2  2026-02-10 16:21:55
+```
+
+
+### Downloading
+
+`s3v cp` will download latest version of file.
+```bash
+$ s3v cp stg-objectlock/s3v/test.txt .
+
+$ cat test.txt 
+3
+```
+
+Give `-i VERSION` to download specific version.
+
+```bash
+$ s3v cp stg-objectlock/s3v/test.txt . -s by0fQCa9Jl7gFgl8vKEjaDvl8z3CSRnD
+  Using version: by0fQCa9Jl7gFgl8vKEjaDvl8z3CSRnD
+$ cat test.txt 
+1
+```
+
+
+### Delete and undelete
+
+`s3v rm` deletes file. After deletion, `aws s3 ls` do not list file, but `s3v ls` still shows it with `[DEL]` tag.
+
+```bash
+$ s3v rm stg-objectlock/s3v/test.txt
+$ aws s3 ls stg-objectlock/s3v/
+$ s3v ls stg-objectlock/s3v/
+Listing objects in bucket 'stg-objectlock' with prefix 's3v/'
+test.txt                                |2026-02-10 16:35:00|              2|   4| [DEL]
+```
+
+If we will see versions for file, we will see special delete marker on S3 (which makes file to be logically 'deleted').
+```bash
+ $ s3v ls stg-objectlock/s3v/test.txt
+Listing objects in bucket 'stg-objectlock' with prefix 's3v/test.txt'
+# Fetching version metadata for bucket: stg-objectlock...
+# Fetched metadata for 215 versions from 153 object(s) in bucket 'stg-objectlock'
+Objects under prefix 's3v/test.txt':
+s3v/test.txt [deleted]
+   by0fQCa9Jl7gFgl8vKEjaDvl8z3CSRnD          2  2026-02-10 16:21:30
+   LHK6nA8Ny5YHNh7TOoH94LDinqCH9Czt          2  2026-02-10 16:21:46
+   iIGXCsBmEKvBq7DhaP09DIzp3fLO9d1H          2  2026-02-10 16:21:55
+   odaXkvFlMoAWwDu_q.K3esuYdHjUpgMg  [DELETED]  2026-02-10 16:40:33
+```
+
+`s3v unrm` will remove "delete marker" and file (latest version) will be available again.
+```bash
+$ s3v unrm stg-objectlock/s3v/test.txt
+
+$ s3v ls stg-objectlock/s3v/
+Listing objects in bucket 'stg-objectlock' with prefix 's3v/'
+test.txt                                |2026-02-10 16:35:00|              2|   3|
+```
+
+### Restore specific version
+To recover specific version of file (make it to be current) use `s3v recover` (or just `s3v r`). Let's recover first version of file.
+
+```bash
+$ s3v recover stg-objectlock/s3v/test.txt . -s by0fQCa9Jl7gFgl8vKEjaDvl8z3CSRnD
+Successfully recovered version by0fQCa9Jl7gFgl8vKEjaDvl8z3CSRnD as current version of s3://stg-objectlock/s3v/test.txt
+
+$ s3v cp stg-objectlock/s3v/test.txt . 
+$ cat test.txt 
+1
+```
+

s3v-0.1.0/README.md

@@ -0,0 +1,117 @@
+# s3v
+Convinient CLI tool to work with versioned S3 buckets. Like `aws s3` or `aws s3api` but much easier to use.
+
+## Installation
+~~~
+# recommended
+pipx install s3v
+
+# or from git
+pipx install git+https://github.com/yaroslaff/s3v
+~~~
+
+## Configuration
+s3v uses boto3, so configuration is same as for `aws` utility (same `~/.aws/` files or `AWS_` shell variables, and optional `--profile NAME` argument)
+
+## Examples
+
+We upload three versions of same file, each one will overwrite old copy. In "ls" we see filename, last modification time, size of latest copy and number of versions in storage.
+
+### Upload
+
+```bash
+$ echo 1 > test.txt 
+$ s3v cp test.txt s3://stg-objectlock/s3v/
+$ echo 2 > test.txt 
+$ s3v cp test.txt s3://stg-objectlock/s3v/
+$ echo 3 > test.txt 
+$ s3v cp test.txt s3://stg-objectlock/s3v/
+```
+You can also give full target name like s3://stg-objectlock/s3v/test.txt. `s3://` prefix is optional ()
+
+
+### List
+Now, list contents of s3v logical 'folder' (all objects with name starting with `s3v/`). If we give full name of object, ls will list all versions.
+
+```bash
+$ s3v ls stg-objectlock/s3v
+Listing objects in bucket 'stg-objectlock' with prefix 's3v'
+test.txt                                |2026-02-10 16:21:55|              2|   3|
+
+$ s3v ls stg-objectlock/s3v/test.txt
+Listing objects in bucket 'stg-objectlock' with prefix 's3v/test.txt'
+Objects under prefix 's3v/test.txt':
+s3v/test.txt
+   by0fQCa9Jl7gFgl8vKEjaDvl8z3CSRnD          2  2026-02-10 16:21:30
+   LHK6nA8Ny5YHNh7TOoH94LDinqCH9Czt          2  2026-02-10 16:21:46
+   iIGXCsBmEKvBq7DhaP09DIzp3fLO9d1H          2  2026-02-10 16:21:55
+```
+
+
+### Downloading
+
+`s3v cp` will download latest version of file.
+```bash
+$ s3v cp stg-objectlock/s3v/test.txt .
+
+$ cat test.txt 
+3
+```
+
+Give `-i VERSION` to download specific version.
+
+```bash
+$ s3v cp stg-objectlock/s3v/test.txt . -s by0fQCa9Jl7gFgl8vKEjaDvl8z3CSRnD
+  Using version: by0fQCa9Jl7gFgl8vKEjaDvl8z3CSRnD
+$ cat test.txt 
+1
+```
+
+
+### Delete and undelete
+
+`s3v rm` deletes file. After deletion, `aws s3 ls` do not list file, but `s3v ls` still shows it with `[DEL]` tag.
+
+```bash
+$ s3v rm stg-objectlock/s3v/test.txt
+$ aws s3 ls stg-objectlock/s3v/
+$ s3v ls stg-objectlock/s3v/
+Listing objects in bucket 'stg-objectlock' with prefix 's3v/'
+test.txt                                |2026-02-10 16:35:00|              2|   4| [DEL]
+```
+
+If we will see versions for file, we will see special delete marker on S3 (which makes file to be logically 'deleted').
+```bash
+ $ s3v ls stg-objectlock/s3v/test.txt
+Listing objects in bucket 'stg-objectlock' with prefix 's3v/test.txt'
+# Fetching version metadata for bucket: stg-objectlock...
+# Fetched metadata for 215 versions from 153 object(s) in bucket 'stg-objectlock'
+Objects under prefix 's3v/test.txt':
+s3v/test.txt [deleted]
+   by0fQCa9Jl7gFgl8vKEjaDvl8z3CSRnD          2  2026-02-10 16:21:30
+   LHK6nA8Ny5YHNh7TOoH94LDinqCH9Czt          2  2026-02-10 16:21:46
+   iIGXCsBmEKvBq7DhaP09DIzp3fLO9d1H          2  2026-02-10 16:21:55
+   odaXkvFlMoAWwDu_q.K3esuYdHjUpgMg  [DELETED]  2026-02-10 16:40:33
+```
+
+`s3v unrm` will remove "delete marker" and file (latest version) will be available again.
+```bash
+$ s3v unrm stg-objectlock/s3v/test.txt
+
+$ s3v ls stg-objectlock/s3v/
+Listing objects in bucket 'stg-objectlock' with prefix 's3v/'
+test.txt                                |2026-02-10 16:35:00|              2|   3|
+```
+
+### Restore specific version
+To recover specific version of file (make it to be current) use `s3v recover` (or just `s3v r`). Let's recover first version of file.
+
+```bash
+$ s3v recover stg-objectlock/s3v/test.txt . -s by0fQCa9Jl7gFgl8vKEjaDvl8z3CSRnD
+Successfully recovered version by0fQCa9Jl7gFgl8vKEjaDvl8z3CSRnD as current version of s3://stg-objectlock/s3v/test.txt
+
+$ s3v cp stg-objectlock/s3v/test.txt . 
+$ cat test.txt 
+1
+```
+

s3v-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "s3v"
+license = { file = "LICENSE" }
+dynamic = ["version"]
+keywords = [
+  "aws", "s3", "versioned", "bucket", "object lock",
+  "retention", "undelete", "recover", "cli"
+]
+authors = [
+  { name = "Yaroslav Polyakov", email = "yaroslaff@gmail.com" },
+]
+description = "Convenient CLI tool to work with versioned (including Object Lock) S3 buckets (recover, undelete, etc.)"
+readme = "README.md"
+requires-python = ">=3.8"
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+dependencies = [
+  "boto3>=1.28.0",
+  "botocore>=1.31.0",  
+]
+
+[project.urls]
+Homepage = "https://github.com/yaroslaff/s3v"
+Issues = "https://github.com/yaroslaff/s3v/issues"
+
+[project.scripts]
+s3v = "s3v.cli.main:main"
+
+[tool.hatch.version]
+path = "s3v/__about__.py"
+
+[tool.hatch.envs]
+py38 = { python = "3.8" }
+py39 = { python = "3.9" }
+py310 = { python = "3.10" }
+py311 = { python = "3.11" }
+py312 = { python = "3.12" }
+
+[tool.hatch.envs.default]
+dependencies = [
+  "coverage[toml]>=6.5",
+  "pytest",
+]
+
+[tool.hatch.envs.default.scripts]
+test = "pytest {args:tests}"
+test-cov = "coverage run -m pytest {args:tests}"
+cov-report = ["coverage report -m"]
+cov = ["test-cov", "cov-report"]
+
+[tool.coverage.report]
+exclude_lines = [
+  "no cov",
+  "if __name__ == '__main__':",
+  "if TYPE_CHECKING:",
+]

s3v-0.1.0/s3v/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

s3v-0.1.0/s3v/aws.py

@@ -0,0 +1,314 @@
+import boto3
+import sys
+import json
+from pathlib import Path
+from botocore.exceptions import NoCredentialsError, ClientError
+from typing import Optional
+
+from .versions import VersionsIndex, VersionedObject
+from .misc import kmgt
+
+
+def normalize_bucket_name(bucket: str) -> tuple:
+    """Parse bucket name and optional prefix from s3:// or bucket/prefix format.
+    
+    Returns:
+        (bucket_name, prefix) tuple
+    """
+    # Remove s3:// prefix if present
+    bucket = bucket.replace("s3://", "")
+    
+    # Split on first / to separate bucket from prefix
+    if "/" in bucket:
+        parts = bucket.split("/", 1)
+        return parts[0], parts[1]
+    
+    # Remove trailing slash only if no prefix
+    return bucket.rstrip("/"), ""
+
+def list_buckets(profile_name=None):
+    """List all S3 buckets."""
+    try:
+        session = boto3.Session(profile_name=profile_name)
+        s3_client = session.client("s3")
+        
+        response = s3_client.list_buckets()
+        buckets = response.get("Buckets", [])
+        
+        if not buckets:
+            print("No buckets found", file=sys.stderr)
+            return
+        
+        print("Available S3 buckets:")
+        for bucket in sorted(buckets, key=lambda x: x["Name"]):
+            creation_date = bucket.get("CreationDate", "").isoformat() if bucket.get("CreationDate") else "Unknown"
+            print(f"  {bucket['Name']:<50} {creation_date}")
+    
+    except NoCredentialsError:
+        print("Error: AWS credentials not found. Configure credentials in ~/.aws/ or set AWS_* environment variables.", file=sys.stderr)
+        raise sys.exit(1)
+    except ClientError as e:
+        print(f"AWS error: {e}", file=sys.stderr)
+        raise sys.exit(1)
+
+def sync_versions(bucket: str, profile_name: str | None = None):
+    """Internal function to sync versions from S3."""
+    cache_dir = Path.home() / ".cache" / "s3v" / bucket
+    cache_dir.mkdir(parents=True, exist_ok=True)
+
+    vi = VersionsIndex(bucket)
+
+    try:
+        session = boto3.Session(profile_name=profile_name)
+        s3_client = session.client("s3")
+
+        print(f"# Fetching version metadata for bucket: {bucket}...")
+
+        paginator = s3_client.get_paginator("list_object_versions")
+        pages = paginator.paginate(Bucket=bucket)
+
+        version_count = 0
+
+        for page in pages:
+            for version in page.get("Versions", []):
+                version['ETag'] = version['ETag'].strip('"')  # Remove quotes from ETag
+                key = version["Key"]
+                vo = vi[key] if key in vi else VersionedObject(key)
+                vo.add_version(version)
+                vi[key] = vo
+                version_count += 1
+
+            for marker in page.get("DeleteMarkers", []):
+                key = marker["Key"]
+                vo = vi[key] if key in vi else VersionedObject(key)
+                vo.add_delete_marker(marker)
+                vi[key] = vo
+                version_count += 1
+
+        vi.save()
+
+        print(f"# Fetched metadata for {version_count} versions from {len(vi)} object(s) in bucket '{bucket}'")
+
+        return vi
+
+
+    except NoCredentialsError:
+        print("Error: AWS credentials not found. Configure credentials in ~/.aws/ or set AWS_* environment variables.", file=sys.stderr)
+        sys.exit(1)
+    except ClientError as e:
+        print(f"AWS error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+def delete_from_s3(s3obj: str, version_id: str | None = None, profile_name: str | None = None):
+    """Delete an object or specific version in S3.
+    
+    If version_id is provided, deletes that specific version.
+    Otherwise, creates a delete marker in versioned buckets or deletes the object.
+    """
+
+
+    bucket, key = normalize_bucket_name(s3obj)
+
+    try:
+        session = boto3.Session(profile_name=profile_name)
+        s3_client = session.client("s3")
+        
+        if version_id:
+            print(f"# Deleting version {version_id} of s3://{bucket}/{key}...")
+            s3_client.delete_object(Bucket=bucket, Key=key, VersionId=version_id)
+            print(f"# Successfully deleted version {version_id} of s3://{bucket}/{key}")
+        else:
+            print(f"# Deleting s3://{bucket}/{key}...")
+            response = s3_client.delete_object(Bucket=bucket, Key=key)
+            
+            if "DeleteMarker" in response and response["DeleteMarker"]:
+                print(f"# Successfully marked s3://{bucket}/{key} as deleted")
+            else:
+                print(f"# Successfully deleted s3://{bucket}/{key}")
+        
+    except NoCredentialsError:
+        print("Error: AWS credentials not found. Configure credentials in ~/.aws/ or set AWS_* environment variables.", file=sys.stderr)
+        raise sys.exit(1)
+    except ClientError as e:
+        print(f"AWS error: {e}", file=sys.stderr)
+        raise sys.exit(1)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        raise sys.exit(1)
+
+def upload_to_s3(source: str, destination: str, profile_name: str | None = None):
+
+
+    """Upload a file to S3."""
+    # Parse source file
+    source_path = Path(source)
+    if not source_path.exists():
+        print(f"Error: File not found: {source}")
+        raise sys.exit(1)
+    
+    if not source_path.is_file():
+        print(f"Error: Not a file: {source}")
+        raise sys.exit(1)
+    
+    # Parse destination
+    bucket, prefix = normalize_bucket_name(destination)
+
+    vi = VersionsIndex(bucket)
+    vi.load()
+
+    # If destination ends with /, append filename to prefix
+    if prefix.endswith("/"):
+        key = prefix + source_path.name
+
+    elif vi.has_directory(prefix):
+        # If prefix is a known directory in VersionsIndex, treat as directory
+        key = prefix.rstrip('/') + "/" + source_path.name
+    elif prefix:
+        # If prefix is not empty and doesn't end with /, treat it as a full path
+        key = prefix
+    else:
+        # If no prefix, just use filename
+        key = source_path.name
+
+    try:
+        session = boto3.Session(profile_name=profile_name)
+        s3_client = session.client("s3")
+        
+        file_size = source_path.stat().st_size
+        size_str = kmgt(file_size) if file_size > 0 else "0B"
+        
+        print(f"# Uploading {source} to s3://{bucket}/{key} ({size_str})...", file=sys.stderr)
+        
+        s3_client.upload_file(str(source_path), bucket, key)
+        
+        print(f"# Successfully uploaded to s3://{bucket}/{key}", file=sys.stderr)
+        
+    except NoCredentialsError:
+        print("Error: AWS credentials not found. Configure credentials in ~/.aws/ or set AWS_* environment variables.", file=sys.stderr)
+        raise sys.exit(1)
+    except ClientError as e:
+        print(f"AWS error: {e}", file=sys.stderr)
+        raise sys.exit(1)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        raise sys.exit(1)
+
+def download_from_s3(s3obj: str, destination: str, version_id: str | None = None, profile_name: str | None = None):
+    """Download a file from S3."""
+    bucket, key = normalize_bucket_name(s3obj)
+    
+    # Parse destination local path
+    dest_path = Path(destination)
+    
+    # If destination is "." (current dir) or ends with "/", use source filename as basename
+    if destination == "." or destination.endswith("/"):
+        dest_path = dest_path / Path(key).name
+    
+    # Create parent directory if needed
+    dest_path.parent.mkdir(parents=True, exist_ok=True)
+    
+    try:
+        session = boto3.Session(profile_name=profile_name)
+        s3_client = session.client("s3")
+        
+        print(f"# Downloading s3://{bucket}/{key} → {dest_path}...")
+        
+        extra_args = {}
+        if version_id:
+            extra_args["VersionId"] = version_id
+            print(f"  Using version: {version_id}")
+        
+        s3_client.download_file(bucket, key, str(dest_path), ExtraArgs=extra_args if extra_args else None)
+        
+        file_size = dest_path.stat().st_size
+        size_str = kmgt(file_size)
+        
+        print(f"# Successfully downloaded ({size_str}) to {str(dest_path)}")
+        
+    except NoCredentialsError:
+        print("Error: AWS credentials not found. Configure credentials in ~/.aws/ or set AWS_* environment variables.", file=sys.stderr)
+        raise sys.exit(1)
+    except ClientError as e:
+        print(f"AWS error: {e}", file=sys.stderr)
+        raise sys.exit(1)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        raise sys.exit(1)
+
+
+def undelete_from_s3(s3obj: str, profile_name: str | None = None):
+    """Undelete an object in S3 (remove the delete marker in versioned buckets)."""
+    bucket, key = normalize_bucket_name(s3obj)
+
+    try:
+        session = boto3.Session(profile_name=profile_name)
+        s3_client = session.client("s3")
+
+        print(f"# Undeleting s3://{bucket}/{key}...")
+
+        # List versions to find the latest delete marker for the key
+        paginator = s3_client.get_paginator("list_object_versions")
+        pages = paginator.paginate(Bucket=bucket, Prefix=key)
+
+        delete_marker_version = None
+        for page in pages:
+            for marker in page.get("DeleteMarkers", []):
+                if marker.get("Key") == key and marker.get("IsLatest"):
+                    delete_marker_version = marker.get("VersionId")
+                    break
+            if delete_marker_version:
+                break
+
+        if not delete_marker_version:
+            print(f"Error: No delete marker found for s3://{bucket}/{key}", file=sys.stderr)
+            raise sys.exit(1)
+
+        # Delete the delete marker by specifying its version ID
+        s3_client.delete_object(Bucket=bucket, Key=key, VersionId=delete_marker_version)
+
+        print(f"# Successfully removed delete marker for s3://{bucket}/{key}", file=sys.stderr)
+
+    except NoCredentialsError:
+        print("Error: AWS credentials not found. Configure credentials in ~/.aws/ or set AWS_* environment variables.", file=sys.stderr)
+        raise sys.exit(1)
+    except ClientError as e:
+        print(f"AWS error: {e}", file=sys.stderr)
+        raise sys.exit(1)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        raise sys.exit(1)
+    
+def recover_object_version(
+    s3obj: str,    
+    version_id: str,
+    profile_name: Optional[str] = None):
+
+
+    bucket, key = normalize_bucket_name(s3obj)
+
+    session = boto3.Session(profile_name=profile_name)
+    s3_client = session.client("s3")
+
+
+    try:
+        # Copy the specific version to itself, making it the current version
+        copy_source = {
+            'Bucket': bucket,
+            'Key': key,
+            'VersionId': version_id
+        }
+        
+        _ = s3_client.copy_object(
+            CopySource=copy_source,
+            Bucket=bucket,
+            Key=key
+        )
+        
+        print(f'Successfully recovered version {version_id} as current version of s3://{bucket}/{key}')
+        
+    except ClientError as e:
+        print(f'Failed to recover version {version_id}: {e}')
+        sys.exit(1)
+        
+
+

s3v-0.1.0/s3v/cli/main.py

@@ -0,0 +1,91 @@
+import argparse
+import sys
+from pathlib import Path
+from botocore.exceptions import NoCredentialsError, ClientError, ParamValidationError
+
+from ..aws import list_buckets, delete_from_s3, upload_to_s3, download_from_s3, undelete_from_s3, recover_object_version
+from ..ls import list_objects
+
+def get_args():    
+    parser = argparse.ArgumentParser(description="S3V CLI")
+    parser.add_argument("COMMAND", choices=["ls", "cp", "rm", "del", "delete", "recover", "rec", "r", "unrm"], help="The command to execute: ls, cp, rm, recover")
+    parser.add_argument("LOCATION1", nargs='?', help="The S3 or local location (e.g. s3://bucket/key or bucket/prefix or arhive.zip)")
+    parser.add_argument("LOCATION2", nargs='?', help="The S3 location for cp command (e.g., s3://bucket/key or bucket/prefix)")
+
+    parser.add_argument("--profile", help="AWS CLI profile to use for authentication")
+    parser.add_argument("-r", "--recursive", action="store_true", default=False, help="List all objects recursively (only for ls command)")
+    parser.add_argument("-s", "--version", metavar='S3_OBJECT_VERSION', help="Version specifier for rm and recover commands")
+    parser.add_argument("-e", "--etag", default=False, action="store_true", help="Print ETag (md5sum) for each version in ls command")
+
+    return parser.parse_args()
+
+def guess_if_upload(loc1: str, loc2: str) -> bool | None:
+    """Guess if the cp command is an upload or download based on the presence of s3:// and existence of local files."""
+    loc1_is_s3 = loc1.startswith("s3://")
+    loc2_is_s3 = loc2.startswith("s3://")
+
+    if loc1_is_s3 and not loc2_is_s3:
+        return False  # Download
+    elif loc2_is_s3 and not loc1_is_s3:
+        return True  # Upload
+    else:
+        # If both are local paths, guess based on file existence
+        if Path(loc1).exists() and not Path(loc2).exists():
+            return True  # Upload
+        elif Path(loc2).exists() and not Path(loc1).exists():
+            return False  # Download
+        else:
+            return None  # Ambiguous, cannot guess
+
+
+
+
+
+def main():
+    args= get_args()
+    
+    try:
+        if args.COMMAND == "ls":
+            if args.LOCATION1 is None:
+                list_buckets(profile_name=args.profile)
+                return
+            
+            list_objects(bucket=args.LOCATION1, profile_name=args.profile, recursive=args.recursive, etag=args.etag)
+            return
+        elif args.COMMAND == "cp":
+            if args.LOCATION1 is None or args.LOCATION2 is None:
+                print("Error: cp command requires both source and destination locations.", file=sys.stderr)
+                return
+            if args.LOCATION1.startswith("s3://") and args.LOCATION2.startswith("s3://"):
+                print("Error: cp command does not support copying between two S3 locations. Please copy to/from local filesystem instead.", file=sys.stderr)
+                return
+            
+            
+            if guess_if_upload(args.LOCATION1, args.LOCATION2):
+                    upload_to_s3(source=args.LOCATION1, destination=args.LOCATION2, profile_name=args.profile)
+                    return
+            else:
+                download_from_s3(s3obj=args.LOCATION1, destination=args.LOCATION2, version_id=args.version, profile_name=args.profile)
+                return                    
+
+        elif args.COMMAND in ["rm", "del", "delete"]:
+            delete_from_s3(s3obj=args.LOCATION1, version_id=args.version, profile_name=args.profile)
+            return
+        elif args.COMMAND in ["recover", "rec", "r", "undelete", "undel", "unrm"]:
+            if args.version:
+                # recover specific version
+                recover_object_version(s3obj=args.LOCATION1, version_id=args.version, profile_name=args.profile)
+            else:
+                # just recover the latest version if version is not specified
+                undelete_from_s3(s3obj=args.LOCATION1, profile_name=args.profile)
+            return
+        else:
+            print("Do not know how to handle command:", args.COMMAND, file=sys.stderr)
+            sys.exit(1)
+
+    except (NoCredentialsError, ClientError, ParamValidationError) as botocore_error:
+        print(f"Botocore Error: {botocore_error}", file=sys.stderr)
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

s3v-0.1.0/s3v/ls.py

@@ -0,0 +1,38 @@
+from pathlib import Path
+import json
+
+from .aws import normalize_bucket_name, sync_versions
+from .versions import VersionsIndex
+
+
+def list_objects(bucket: str, prefix: str = "", profile_name=None, recursive: bool = False, etag: bool = False):
+    """List objects in a specific S3 bucket and prefix."""
+
+    bucket, prefix = normalize_bucket_name(bucket)
+    print(f"Listing objects in bucket '{bucket}' with prefix '{prefix}'")
+    vi = sync_versions(bucket, profile_name=profile_name)
+
+    # vi.dump()
+
+    # vi = VersionsIndex.load_from_file(Path.home() / ".cache" / "s3v" / bucket / "versions.json")
+
+
+    # exact match
+    if prefix in vi:
+        print(f"Objects under prefix '{prefix}':")
+        vo = vi[prefix]
+        #print("OLD:")
+        #print(json.dumps(vo.serialize(), indent=2))
+        #print()
+        #print("NEW:")
+        print(vo.ls_versions(strip_prefix=prefix, etag=etag))
+        return
+
+    # prefix list
+
+    if prefix and not prefix.endswith("/"):
+        prefix += "/"
+
+    for key in sorted(vi.keys()):
+        if key.startswith(prefix):
+            print(vi[key].ls_1line(strip_prefix=prefix))

s3v-0.1.0/s3v/misc.py

@@ -0,0 +1,11 @@
+def kmgt(sz: int) -> str:
+    """Convert bytes to human-readable format."""
+    if sz < 1024:
+        return f"{sz}"
+
+    for unit in ["B", "KB", "MB", "GB", "TB"]:
+        if sz < 1024:
+            return f"{sz:.1f}{unit}"
+        sz /= 1024
+    return f"{sz:.1f}PB"
+

s3v-0.1.0/s3v/versions.py

@@ -0,0 +1,183 @@
+from typing import Dict, Any
+from pathlib import Path
+import json
+from datetime import datetime
+from .misc import kmgt
+
+
+def serialize_version(version_record: Dict) -> Dict:
+    # replace LastModified to string
+    # make copy of object to avoid mutating original
+    version_record = version_record.copy()
+    version_record["LastModified"] = version_record["LastModified"].isoformat()
+    return version_record
+
+def unserialize_version(version_data: Dict) -> Dict:
+    version_data = version_data.copy()
+    version_data["LastModified"] = datetime.fromisoformat(version_data["LastModified"])
+    return version_data
+
+
+class VersionedObject:
+    def __init__(self, key: str):
+        self.key = key
+        self.versions = dict()  # version_id -> metadata dict
+        self.delete_markers = dict()
+    
+    def add_version(self, version_record: Dict):
+        version_id = version_record["VersionId"]
+        self.versions[version_id] = version_record
+
+
+    def add_delete_marker(self, delete_marker_record: Dict):
+        version_id = delete_marker_record["VersionId"]
+        self.delete_markers[version_id] = delete_marker_record
+    
+    def serialize(self) -> Dict[str, Any]:
+        return {
+            "versions": [serialize_version(v) for v in self.versions.values()],
+            "delete_markers": [serialize_version(dm) for dm in self.delete_markers.values()]
+        }
+    
+    def __repr__(self) -> str:
+        return f"VersionedObject(key={self.key}, versions={len(self.versions)}, delete_markers={len(self.delete_markers)})"
+
+
+    def dump(self):
+        for version in self.versions.values():
+            print(f"  Version: {version}")
+        for dm in self.delete_markers.values():
+            print(f"  Delete Marker: {dm}")
+
+    def get_latest_version(self) -> Dict | None:
+        if not self.versions:
+            return None
+        return max(self.versions.values(), key=lambda v: v["LastModified"])
+
+    def ls_1line(self, strip_prefix: str | None = None) -> str:
+        latest_version = self.get_latest_version()
+        if latest_version is None:
+            return f"{self.key} (deleted, no versions)"
+        
+
+        if strip_prefix and self.key.startswith(strip_prefix):
+            display_key = self.key[len(strip_prefix):]
+        else:            
+            display_key = self.key
+
+        deleted = self.is_deleted()
+        status = " [DEL]" if deleted else " "
+        return f"{display_key:40}|{latest_version['LastModified'].strftime("%Y-%m-%d %H:%M:%S"):5}|{kmgt(latest_version['Size']):>15}| {len(self.versions):>3}|{status}"
+
+
+    def ls_versions(self, strip_prefix: str | None = None, etag: bool = False) -> str:
+        out = ''
+        if self.is_deleted():
+            out += f"{self.key} [deleted]\n"
+        else:
+            out += f"{self.key}\n"
+
+        for version in sorted(self.versions.values(), key=lambda v: v["LastModified"]):
+            if strip_prefix and self.key.startswith(strip_prefix):
+                display_key = self.key[len(strip_prefix):]
+            else:
+                display_key = self.key
+            out += f"  {display_key} {version['VersionId']} {kmgt(version['Size']):>10}  {version['LastModified'].strftime('%Y-%m-%d %H:%M:%S')}"
+            if etag:                
+                out += f"  {version['ETag']}"
+            out += "\n"
+        
+        for dm in sorted(self.delete_markers.values(), key=lambda dm: dm["LastModified"]):
+            if strip_prefix and self.key.startswith(strip_prefix):
+                display_key = self.key[len(strip_prefix):]
+            else:
+                display_key = self.key
+            if dm['IsLatest']:
+                deleted_str = "[DELETED]"
+            else:                
+                deleted_str = "[OLD DM]"
+            out += f"  {display_key} {dm['VersionId']} {deleted_str:>10}  {dm['LastModified'].strftime('%Y-%m-%d %H:%M:%S')}\n"
+        
+        return out
+
+    def is_deleted(self) -> bool:       
+        # if any IsLatest in delete markers is true, consider it deleted
+        return any(dm.get("IsLatest", False) for dm in self.delete_markers.values())    
+
+class VersionsIndex:
+    """In-memory representation of the versions metadata JSON.
+
+    This class contains no AWS code and only operates on the JSON structure
+    produced by `_sync_versions` (mapping of key -> {"versions": [...], "delete_markers": [...]}).
+    """
+
+    bucket_keys: Dict[str, VersionedObject]
+
+    def __init__(self, bucketname: str):
+        self.bucket_keys = dict()
+        self.bucketname = bucketname
+
+
+    def save(self):
+        cache_dir = Path.home() / ".cache" / "s3v" 
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        cach_file = cache_dir / f"{self.bucketname}.json"
+
+        with open(cach_file, "w") as f:
+            json.dump({key: vo.serialize() for key, vo in self.bucket_keys.items()}, f, indent=2)
+
+    def load(self):
+        cache_dir = Path.home() / ".cache" / "s3v" 
+        cach_file = cache_dir / f"{self.bucketname}.json"
+
+        if not cach_file.exists():
+            return
+
+        with open(cach_file, "r") as f:
+            raw_data = json.load(f)
+            for key, vo_data in raw_data.items():
+                vo = VersionedObject(key)
+                for version_record in vo_data.get("versions", []):
+                    vo.add_version(unserialize_version(version_record))
+                for delete_marker_record in vo_data.get("delete_markers", []):
+                    vo.add_delete_marker(unserialize_version(delete_marker_record))
+                self.bucket_keys[key] = vo
+
+
+    def keys(self):
+        return list(self.bucket_keys.keys())
+
+    def get(self, key: str):
+        return self.bucket_keys.get(key)
+
+    def __setitem__(self, key: str, value: VersionedObject):
+        self.bucket_keys[key] = value
+
+    def __getitem__(self, key: str) -> VersionedObject:
+        return self.bucket_keys[key]
+    
+    def __contains__(self, key: str):
+        return key in self.bucket_keys
+
+    # len()
+    def __len__(self):
+        return len(self.bucket_keys)
+    
+    def __repr__(self) -> str:
+        return f"VersionsIndex(bucket={self.bucketname}, keys={len(self.bucket_keys)})"
+
+    def has_directory(self, dirname: str) -> bool:
+        """Check if any key starts with the given directory name."""
+        prefix = dirname
+        if not prefix.endswith("/"):
+            prefix += "/"
+        for key in self.bucket_keys.keys():
+            if key.startswith(prefix):
+                return True
+        return False
+
+    def dump(self):
+        for key, vo in self.bucket_keys.items():
+            print(f"{key}")
+            vo.dump()
+            print()