initial commit

.dockerignore

@@ -0,0 +1,6 @@
+/.venv
+__pycache__
+*.egg-info
+*.pyc
+/dist
+/.mypy_cache

.github/workflows/release.yml

@@ -0,0 +1,91 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+    tags: ["*"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install requirements
+        run: |
+          python -Im pip install --upgrade pip
+          python -Im pip install build check-wheel-contents
+      - name: Build package
+        run: python -Im build
+      - name: Check wheel content
+        run: check-wheel-contents dist/*.whl
+      - name: Print package contents summary
+        run: |
+          echo -e '<details open><summary>SDist Contents</summary>\n' >> $GITHUB_STEP_SUMMARY
+          tar -tf dist/*.tar.gz | tree -a --fromfile . | sed 's/^/    /' | tee -a $GITHUB_STEP_SUMMARY
+          echo -e '</details>\n' >> $GITHUB_STEP_SUMMARY
+          echo -e '<details open><summary>Wheel Contents</summary>\n' >> $GITHUB_STEP_SUMMARY
+          unzip -Z1 dist/*.whl | tree -a --fromfile . | sed 's/^/    /' | tee -a $GITHUB_STEP_SUMMARY
+          echo -e '</details>\n' >> $GITHUB_STEP_SUMMARY
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: ./dist
+
+  # Draft a new release on tagged commit on main.
+  draft-release:
+    name: Draft release
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
+    needs: [build]
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+      - name: Draft a new release
+        run: >
+          gh release create --draft --repo ${{ github.repository }}
+          ${{ github.ref_name }}
+          dist/*
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+  # Publish to PyPI on tagged commit on main.
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
+    needs: [build]
+    environment:
+      name: publish-pypi
+      url: https://pypi.org/project/pyforce-p4/${{ github.ref_name }}
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+      - name: Upload package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  # Publish to Test PyPI on every commit on main.
+  publish-test-pypi:
+    name: Publish to Test PyPI
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: [build]
+    environment: publish-test-pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+      - name: Upload package to Test PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

.github/workflows/style.yml

@@ -0,0 +1,45 @@
+name: Code style
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Cancel concurent in-progress jobs or run on pull_request
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  ruff-lint:
+    name: Ruff lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install requirements
+        run: |
+          python -Im pip install --upgrade pip
+          python -Im pip install ruff
+      - name: Run Ruff linter
+        run: python -Im ruff check --output-format=github src tests
+
+  ruff-format:
+    name: Ruff format diff
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install requirements
+        run: |
+          python -Im pip install --upgrade pip
+          python -Im pip install ruff
+      - name: Run Ruff formatter
+        run: python -Im ruff format --diff src tests

.github/workflows/tests.yml

@@ -0,0 +1,93 @@
+name: Tests and type checking
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+# TODO: pages
+# TODO: build
+# TODO: publish
+
+jobs:
+  mypy:
+    name: Mypy ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - "3.8"
+          - "3.9"
+          - "3.10"
+          - "3.11"
+          - "3.12"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install requirements
+        run: |
+          python -Im pip install --upgrade pip
+          python -Im pip install .[mypy]
+      - name: Run mypy
+        run: |
+          python -Im mypy src tests
+
+  tests:
+    name: Tests ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - "3.8"
+          - "3.9"
+          - "3.10"
+          - "3.11"
+          - "3.12"
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build image
+        run: docker build --build-arg="PYTHON_VERSION=${{ matrix.python-version }}" -t local .
+      - name: Run tests
+        run: |
+          docker run --name test local "python -m coverage run -p -m pytest && mkdir cov && mv .coverage.* cov"
+          docker cp test:/app/cov/. .
+      - name: Upload coverage data
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-data-${{ matrix.python-version }}
+          path: .coverage.*
+          if-no-files-found: ignore
+
+  coverage:
+    name: Combine and report coverage
+    runs-on: ubuntu-latest
+    needs: tests
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Download coverage data
+        uses: actions/download-artifact@v4
+        with:
+          pattern: coverage-data-*
+          merge-multiple: true
+      - name: Install requirements
+        run: |
+          python -Im pip install --upgrade pip
+          python -Im pip install coverage
+      - name: Combine coverage and report
+        run: |
+          python -Im coverage combine
+          # Report in summary
+          python -Im coverage report --show-missing --skip-covered --skip-empty --format=markdown >> $GITHUB_STEP_SUMMARY
+          # Report in console
+          python -Im coverage report --show-missing --skip-covered --skip-empty
+

.gitignore

@@ -0,0 +1,8 @@
+/.venv
+__pycache__
+*.egg-info
+/.python-version
+*.pyc
+/dist
+/docs/_build
+/.coverage

CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing
+
+## Makefile commands
+
+This project include a [Makefile](https://www.gnu.org/software/make/)
+containing the most common commands used when developing.
+
+```text
+$ make help
+build          Build project
+clean          Clear local caches and build artifacts
+doc            Build documentation
+formatdiff     Show what the formatting would look like
+help           Display this message
+install        Install the package and dependencies for local development
+interactive    Run an interactive docker container
+linkcheck      Check all external links in docs for integrity
+lint           Run linter
+mypy           Perform type-checking
+serve          Serve documentation at http://127.0.0.1:8000
+tests          Run the tests with coverage in a docker container
+uninstall      Remove development environment
+```
+
+## Running the tests
+
+The tests require a new `p4d` server running in the backgound.
+To simplify the development, tests are runned in a docker container generated from this [Dockerfile](Dockerfile).
+
+This target `make tests` target build the container and run the tests + coverage inside.

Dockerfile

@@ -0,0 +1,38 @@
+# Installation:
+# https://www.perforce.com/manuals/p4sag/Content/P4SAG/install.linux.packages.install.html
+
+# Post-installation configuration:
+# https://www.perforce.com/manuals/p4sag/Content/P4SAG/install.linux.packages.configure.html
+
+# Example perforce server:
+# https://github.com/ambakshi/docker-perforce/tree/master/perforce-server
+
+# Dockerfile from sourcegraph:
+# https://github.com/sourcegraph/helix-docker/tree/main
+
+# Making a Perforce Server with Docker compose
+# https://aricodes.net/posts/perforce-server-with-docker/
+ARG PYTHON_VERSION=3.11
+FROM python:$PYTHON_VERSION
+
+# Update Ubuntu and add Perforce Package Source
+# Add the perforce public key to our keyring
+# Add perforce repository to our APT config
+RUN apt-get update && \
+  apt-get install -y wget gnupg2 && \
+  wget -qO - https://package.perforce.com/perforce.pubkey | apt-key add - && \
+  echo "deb http://package.perforce.com/apt/ubuntu focal release" > /etc/apt/sources.list.d/perforce.list && \
+  apt-get update
+
+# Install helix-p4d, which installs p4d, p4, p4dctl, and a configuration script.
+RUN apt-get update && apt-get install -y helix-p4d
+
+WORKDIR /app
+
+RUN python -m pip install pytest coverage
+
+COPY . .
+
+RUN python -m pip install --editable .
+
+ENTRYPOINT ["/bin/sh", "-c"]

LICENSE

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