✨NEW: Initial Commit

.github/workflows/tests.yml

@@ -0,0 +1,78 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags:
+      - 'v*'
+  pull_request:
+
+jobs:
+
+  pre-commit:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python
+      uses: actions/setup-python@v1
+      with:
+        python-version: 3.8
+    - uses: pre-commit/action@v2.0.0
+
+  tests:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        python-version: [3.6, 3.7, 3.8, 3.9]
+        os: [ubuntu-latest, windows-latest]
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Installation (deps and package)
+      # we install with flit --pth-file,
+      # so that coverage will be recorded for the module
+      run: |
+        pip install flit
+        flit install --deps=production --extras=test --pth-file
+
+    - name: Run pytest
+      run: |
+        pytest --cov=archive_path --cov-report=xml --cov-report=term-missing
+
+    - name: Upload to Codecov
+      if: matrix.os == 'ubuntu-latest' && matrix.python-version == 3.7
+      uses: codecov/codecov-action@v1
+      with:
+        name: pytests
+        flags: pytests
+        file: ./coverage.xml
+        fail_ci_if_error: true
+
+  publish:
+    name: Publish to PyPi
+    needs: [pre-commit, tests]
+    if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags')
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout source
+      uses: actions/checkout@v2
+    - name: Set up Python
+      uses: actions/setup-python@v1
+      with:
+        python-version: 3.8
+    - name: install flit
+      run: |
+        pip install flit~=3.0
+    - name: Build and publish
+      run: |
+        flit publish
+      env:
+        FLIT_USERNAME: __token__
+        FLIT_PASSWORD: ${{ secrets.PYPI_KEY }}

.gitignore

@@ -127,3 +127,6 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+# VS Code
+.vscode/

.pre-commit-config.yaml

@@ -0,0 +1,50 @@
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v3.2.0
+  hooks:
+  - id: end-of-file-fixer
+  - id: mixed-line-ending
+  - id: trailing-whitespace
+  - id: check-yaml
+  - id: check-toml
+- repo: https://github.com/executablebooks/mdformat
+  rev: 0.4.0
+  hooks:
+  - id: mdformat
+    additional_dependencies:
+    - mdformat-black
+- repo: https://github.com/pre-commit/pygrep-hooks
+  rev: v1.6.0
+  hooks:
+  - id: python-check-blanket-noqa
+- repo: https://github.com/timothycrosley/isort
+  rev: 5.5.3
+  hooks:
+  - id: isort
+-   repo: https://github.com/ikamensh/flynt/
+    rev: '0.55'
+    hooks:
+    -   id: flynt
+        args: [
+            '--line-length=120',
+            '--fail-on-change',
+        ]
+- repo: https://github.com/psf/black
+  rev: 20.8b1
+  hooks:
+  - id: black
+- repo: https://gitlab.com/pycqa/flake8
+  rev: 3.8.3
+  hooks:
+  - id: flake8
+    additional_dependencies:
+    - flake8-bugbear==20.1.4
+    - flake8-builtins==1.5.3
+    - flake8-comprehensions==3.2.3
+    - flake8-rst-docstrings==0.0.14
+    - flake8-markdown==0.2.0
+-   repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v0.780
+    hooks:
+    -   id: mypy
+        pass_filenames: true

README.md

@@ -1,2 +1,115 @@
 # archive-path
-A packkage to provive pathlib like access to zip & tar archives
+
+[![Build Status][ci-badge]][ci-link]
+[![codecov.io][cov-badge]][cov-link]
+[![PyPI version][pypi-badge]][pypi-link]
+
+A package to provide pathlib like access to zip & tar archives.
+
+## Usage
+
+For reading zip (`ZipPath`) or tar (`TarPath`) files:
+
+```python
+from archive_path import TarPath, ZipPath
+
+path = TarPath("path/to/file.tar.gz", mode="r:gz")
+
+sub_path = path / "folder" / "file.txt"
+assert sub_path.filepath == "path/to/file.tar.gz"
+assert sub_path.at == "folder/file.txt"
+assert sub_path.exists() and sub_path.is_file()
+assert sub_path.parent.is_dir()
+content = sub_path.read_text()
+
+for sub_path in path.iterdir():
+    print(sub_path)
+```
+
+For writing files, you should use within a context manager, or directly call the `close` method:
+
+```python
+with TarPath("path/to/file.tar.gz", mode="w:gz") as path:
+
+    (path / "new_file.txt").write_text("hallo world")
+    # there are also some features equivalent to shutil
+    (path / "other_file.txt").putfile("path/to/external_file.txt")
+    (path / "other_folder").puttree("path/to/external_folder", pattern="**/*")
+```
+
+Note that archive formats do not allow to overwrite existing files (they will raise a `FileExistsError`).
+
+For performant access to single files:
+
+```python
+from archive_path import read_file_in_tar, read_file_in_zip
+
+content = read_file_in_tar("path/to/file.tar.gz", "file.txt", encoding="utf8")
+```
+
+These methods allow for faster access to files (using less RAM) in archives containing 1000's of files.
+This is because, the archive's file index is only read until the path is found (discarding non-matches),
+rather than the standard `tarfile`/`zipfile` approach that is to read the entire index into memory first.
+
+## Windows compatibility
+
+Paths within the archives are **always** read and written as being `/` delimited.
+This means that the package works on Windows,
+but will not be compatible with archives written outside this package with `\\` path delimiters.
+
+## Development
+
+This package utilises [flit](https://flit.readthedocs.io) as the build engine, and [tox](https://tox.readthedocs.io) for test automation.
+
+To install these development dependencies:
+
+```bash
+pip install tox
+```
+
+To run the tests:
+
+```bash
+tox
+```
+
+and with test coverage:
+
+```bash
+tox -e py37-cov
+```
+
+The easiest way to write tests, is to edit tests/fixtures.md
+
+To run the code formatting and style checks:
+
+```bash
+tox -e py37-pre-commit
+```
+
+or directly
+
+```bash
+pip install pre-commit
+pre-commit run --all
+```
+
+## Publish to PyPi
+
+Either use flit directly:
+
+```bash
+pip install flit
+flit publish
+```
+
+or trigger the GitHub Action job, by creating a release with a tag equal to the version, e.g. `v0.1.1`.
+
+Note, this requires generating an API key on PyPi and adding it to the repository `Settings/Secrets`, under the name `PYPI_KEY`.
+
+[ci-badge]: https://github.com/aiidateam/archive-path/workflows/CI/badge.svg?branch=main
+[ci-link]: https://github.com/aiidateam/mdformat/actions?query=workflow%3ACI+branch%3Amain+event%3Apush
+[cov-badge]: https://codecov.io/gh/aiidateam/archive-path/branch/main/graph/badge.svg
+[cov-link]: https://codecov.io/gh/aiidateam/archive-path
+[pypi-badge]: https://img.shields.io/pypi/v/archive-path.svg
+[pypi-link]: https://pypi.org/project/archive-path

archive_path/__init__.py

@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+###########################################################################
+# Copyright (c), The AiiDA team. All rights reserved.                     #
+#                                                                         #
+# The code is hosted at https://github.com/aiidateam/archive-path         #
+# For further information on the license, see the LICENSE file            #
+###########################################################################
+"""A package to provide pathlib like access to zip & tar archives."""
+from .tar_path import *  # noqa: F401,F403
+from .zip_path import *  # noqa: F401,F403
+
+__version__ = "0.1.0"

archive_path/common.py

@@ -0,0 +1,52 @@
+# -*- coding: utf-8 -*-
+###########################################################################
+# Copyright (c), The AiiDA team. All rights reserved.                     #
+#                                                                         #
+# The code is hosted at https://github.com/aiidateam/archive-path         #
+# For further information on the license, see the LICENSE file            #
+###########################################################################
+"""Shared code."""
+import itertools
+import posixpath
+from typing import Iterable
+
+
+def _parents(path: str) -> Iterable[str]:
+    """
+    Given a path with elements separated by
+    posixpath.sep, generate all parents of that path.
+
+    >>> list(_parents('b/d'))
+    ['b']
+    >>> list(_parents('/b/d/'))
+    ['/b']
+    >>> list(_parents('b/d/f/'))
+    ['b/d', 'b']
+    >>> list(_parents('b'))
+    []
+    >>> list(_parents(''))
+    []
+    """
+    return itertools.islice(_ancestry(path), 1, None)
+
+
+def _ancestry(path: str) -> Iterable[str]:
+    """
+    Given a path with elements separated by
+    posixpath.sep, generate all elements of that path
+
+    >>> list(_ancestry('b/d'))
+    ['b/d', 'b']
+    >>> list(_ancestry('/b/d/'))
+    ['/b/d', '/b']
+    >>> list(_ancestry('b/d/f/'))
+    ['b/d/f', 'b/d', 'b']
+    >>> list(_ancestry('b'))
+    ['b']
+    >>> list(_ancestry(''))
+    []
+    """
+    path = path.rstrip(posixpath.sep)
+    while path and path != posixpath.sep:
+        yield path
+        path, _ = posixpath.split(path)

archive_path/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561