python-package-folder 0.1.0__tar.gz

python_package_folder-0.1.0/.copier-answers.yml

@@ -0,0 +1,9 @@
+# Changes here will be overwritten by Copier. Do not edit manually.
+_commit: v0.2.19
+_src_path: gh:jlevy/simple-modern-uv
+package_author_email: work@alelom.com
+package_author_name: Alessio Lombardi
+package_description: ''
+package_github_org: alelom
+package_module: python_package_folder
+package_name: python-package-folder

python_package_folder-0.1.0/.cursor/rules/general.mdc

@@ -0,0 +1,72 @@
+---
+description: General Guidelines
+globs: 
+alwaysApply: true
+---
+# Assistant Rules
+
+**Your fundamental responsibility:** Remember you are a senior engineer and have a
+serious responsibility to be clear, factual, think step by step and be systematic,
+express expert opinion, and make use of the user’s attention wisely.
+
+**Rules must be followed:** It is your responsibility to carefully read these rules as
+well as Python or other language-specific rules included here.
+
+Therefore:
+
+- Be concise. State answers or responses directly, without extra commentary.
+  Or (if it is clear) directly do what is asked.
+
+- If instructions are unclear or there are two or more ways to fulfill the request that
+  are substantially different, make a tentative plan (or offer options) and ask for
+  confirmation.
+
+- If you can think of a much better approach that the user requests, be sure to mention
+  it. It’s your responsibility to suggest approaches that lead to better, simpler
+  solutions.
+
+- Give thoughtful opinions on better/worse approaches, but NEVER say “great idea!”
+  or “good job” or other compliments, encouragement, or non-essential banter.
+  Your job is to give expert opinions and to solve problems, not to motivate the user.
+
+- Avoid gratuitous enthusiasm or generalizations.
+  Use thoughtful comparisons like saying which code is “cleaner” but don’t congratulate
+  yourself. Avoid subjective descriptions.
+  For example, don’t say “I’ve meticulously improved the code and it is in great shape!”
+  That is useless generalization.
+  Instead, specifically say what you’ve done, e.g., "I’ve added types, including
+  generics, to all the methods in `Foo` and fixed all linter errors."
+
+# General Coding Guidelines
+
+## Using Comments
+
+- Keep all comments concise and clear and suitable for inclusion in final production.
+
+- DO use comments whenever the intent of a given piece of code is subtle or confusing or
+  avoids a bug or is not obvious from the code itself.
+
+- DO NOT repeat in comments what is obvious from the names of functions or variables or
+  types.
+
+- DO NOT include comments that reflect what you did, such as “Added this function” as
+  this is meaningless to anyone reading the code later.
+  (Instead, describe in your message to the user any other contextual information.)
+
+- DO NOT use fancy or needlessly decorated headings like “===== MIGRATION TOOLS =====”
+  in comments
+
+- DO NOT number steps in comments.
+  These are hard to maintain if the code changes.
+  NEVER DO THIS: “// Step 3: Fetch the data from the cache”\
+  This is fine: “// Now fetch the data from the cache”
+
+- DO NOT use emojis or special unicode characters like ① or • or – or — in comments.
+
+- Use emojis in output if it enhances the clarity and can be done consistently.
+  You may use ✔︎ and ✘ to indicate success and failure, and ∆ and ‼︎ for user-facing
+  warnings and errors, for example, but be sure to do it consistently.
+  DO NOT use emojis gratuitously in comments or output.
+  You may use then ONLY when they have clear meanings (like success or failure).
+  Unless the user says otherwise, avoid emojis and Unicode in comments as clutters the
+  output with little benefit.

python_package_folder-0.1.0/.cursor/rules/python.mdc

@@ -0,0 +1,290 @@
+---
+description: Python Coding Guidelines
+globs: *.py,pyproject.toml
+alwaysApply: false
+---
+# Python Coding Guidelines
+
+These are rules for a modern Python project using uv.
+
+## Python Version
+
+Write for Python 3.11-3.13. Do NOT write code to support earlier versions of Python.
+Always use modern Python practices appropriate for Python 3.11-3.13.
+
+Always use full type annotations, generics, and other modern practices.
+
+## Project Setup and Developer Workflows
+
+- Important: BE SURE you read and understand the project setup by reading the
+  pyproject.toml file and the Makefile.
+
+- ALWAYS use uv for running all code and managing dependencies.
+  Never use direct `pip` or `python` commands.
+
+- Use modern uv commands: `uv sync`, `uv run ...`, etc.
+  Prefer `uv add` over `uv pip install`.
+
+- You may use the following shortcuts
+  ```shell
+  
+  # Install all dependencies:
+  make install
+  
+  # Run linting (with ruff) and type checking (with basedpyright).
+  # Note when you run this, ruff will auto-format and sort imports, resolving any
+  # linter warnings about import ordering:
+  make lint
+  
+  # Run tests:
+  make test
+  
+  # Run uv sync, lint, and test in one command:
+  make
+  ```
+
+- The usual `make test` like standard pytest does not show test output.
+  Run individual tests and see output with `uv run pytest -s some/file.py`.
+
+- Always run `make lint` and `make test` to check your code after changes.
+
+- You must verify there are zero linter warnings/errors or test failures before
+  considering any task complete.
+
+## General Development Practices
+
+- Be sure to resolve the pyright (basedpyright) linter errors as you develop and make
+  changes.
+
+- If type checker errors are hard to resolve, you may add a comment `# pyright: ignore`
+  to disable Pyright warnings or errors but ONLY if you know they are not a real problem
+  and are difficult to fix.
+
+- In special cases you may consider disabling it globally it in pyproject.toml but YOU
+  MUST ASK FOR CONFIRMATION from the user before globally disabling lint or type checker
+  rules.
+
+- Never change an existing comment, pydoc, or a log statement, unless it is directly
+  fixing the issue you are changing, or the user has asked you to clean up the code.
+  Do not drop existing comments when editing code!
+  And do not delete or change logging statements.
+
+## Coding Conventions and Imports
+
+- Always use full, absolute imports for paths.
+  do NOT use `from .module1.module2 import ...`. Such relative paths make it hard to
+  refactor. Use `from toplevel_pkg.module1.modlule2 import ...` instead.
+
+- Be sure to import things like `Callable` and other types from the right modules,
+  remembering that many are now in `collections.abc` or `typing_extensions`. For
+  example: `from collections.abc import Callable, Coroutine`
+
+- Use `typing_extensions` for things like `@override` (you need to use this, and not
+  `typing` since we want to support Python 3.11).
+
+- Add `from __future__ import annotations` on files with types whenever applicable.
+
+- Use pathlib `Path` instead of strings.
+  Use `Path(filename).read_text()` instead of two-line `with open(...)` blocks.
+
+- Use strif’s `atomic_output_file` context manager when writing files to ensure output
+  files are written atomically.
+
+## Use Modern Python Practices
+
+- ALWAYS use `@override` decorators to override methods from base classes.
+  This is a modern Python practice and helps avoid bugs.
+
+## Testing
+
+- For longer tests put them in a file like `tests/test_somename.py` in the `tests/`
+  directory (or `tests/module_name/test_somename.py` file for a submodule).
+
+- For simple tests, prefer inline functions in the original code file below a `## Tests`
+  comment. This keeps the tests easy to maintain and close to the code.
+  Inline tests should NOT import pytest or pytest fixtures as we do not want runtime
+  dependency on pytest.
+
+- DO NOT write one-off test code in extra files that are throwaway.
+
+- DO NOT put `if __name__ == "__main__":` just for quick testing.
+  Instead use the inline function tests and run them with `uv run pytest`.
+
+- You can run such individual tests with `uv run pytest -s src/.../path/to/test`
+
+- Don’t add docs to assertions unless it’s not obvious what they’re checking - the
+  assertion appears in the stack trace.
+  Do NOT write `assert x == 5, "x should be 5"`. Do NOT write `assert x == 5 # Check if
+  x is 5`. That is redundant.
+  Just write `assert x == 5`.
+
+- DO NOT write trivial or obvious tests that are evident directly from code, such as
+  assertions that confirm the value of a constant setting.
+
+- NEVER write `assert False`. If a test reaches an unexpected branch and must fail
+  explicitly, `raise AssertionError("Some explanation")` instead.
+  This is best typical best practice in Python since assertions can be removed with
+  optimization.
+
+- DO NOT use pytest fixtures like parameterized tests or expected exception decorators
+  unless absolutely necessary in more complex tests.
+  It is typically simpler to use simple assertions and put the checks inside the test.
+  This is also preferable because then simple tests have no explicit pytest dependencies
+  and can be placed in code anywhere.
+
+- DO NOT write trivial tests that test something we know already works, like
+  instantiating a Pydantic object.
+
+  ```python
+  class Link(BaseModel):
+    url: str
+    title: str = None
+  
+  # DO NOT write tests like this. They are trivial and only create clutter!
+  def test_link_model():
+    link = Link(url="https://example.com", title="Example")
+    assert link.url == "https://example.com"
+    assert link.title == "Example"
+  ```
+
+## Types and Type Annotations
+
+- Use modern union syntax: `str | None` instead of `Optional[str]`, `dict[str]` instead
+  of `Dict[str]`, `list[str]` instead of `List[str]`, etc.
+
+- Never use/import `Optional` for new code.
+
+- Use modern enums like `StrEnum` if appropriate.
+
+- One exception to common practice on enums: If an enum has many values that are
+  strings, and they have a literal value as a string (like in a JSON protocol), it’s
+  fine to use lower_snake_case for enum values to match the actual value.
+  This is more readable than LONG_ALL_CAPS_VALUES, and you can simply set the value to
+  be the same as the name for each.
+  For example:
+  ```python
+  class MediaType(Enum):
+    """
+    Media types. For broad categories only, to determine what processing
+    is possible.
+    """
+  
+    text = "text"
+    image = "image"
+    audio = "audio"
+    video = "video"
+    webpage = "webpage"
+    binary = "binary"
+  ```
+
+## Guidelines for Literal Strings
+
+- For multi-line strings NEVER put multi-line strings flush against the left margin.
+  ALWAYS use a `dedent()` function to make it more readable.
+  You may wish to add a `strip()` as well.
+  Example:
+  ```python
+  from textwrap import dedent
+  markdown_content = dedent("""
+      # Title 1
+      Some text.
+      ## Subtitle 1.1
+      More text.
+      """).strip()
+  ```
+
+## Guidelines for Comments
+
+- Comments should be EXPLANATORY: Explain *WHY* something is done a certain way and not
+  just *what* is done.
+
+- Comments should be CONCISE: Remove all extraneous words.
+
+- DO NOT use comments to state obvious things or repeat what is evident from the code.
+  Here is an example of a comment that SHOULD BE REMOVED because it simply repeats the
+  code, which is distracting and adds no value:
+  ```python
+  if self.failed == 0:
+      # All successful
+      return "All tasks finished successfully"
+  ```
+
+## Guidelines for Docstrings
+
+- Here is an example of the correct style for docstrings:
+  ```python
+  def check_if_url(
+      text: UnresolvedLocator, only_schemes: list[str] | None = None
+  ) -> ParseResult | None:
+      """
+      Convenience function to check if a string or Path is a URL and if so return
+      the `urlparse.ParseResult`.
+  
+      Also returns false for Paths, so that it's easy to use local paths and URLs
+      (`Locator`s) interchangeably. Can provide `HTTP_ONLY` or `HTTP_OR_FILE` to
+      restrict to only certain schemes.
+      """
+      # Function body
+  
+  def is_url(text: UnresolvedLocator, only_schemes: list[str] | None = None) -> bool:
+      """
+      Check if a string is a URL. For convenience, also returns false for
+      Paths, so that it's easy to use local paths and URLs interchangeably.
+      """
+      return check_if_url(text, only_schemes) is not None
+  ```
+
+- Use concise pydoc strings with triple quotes on their own lines.
+
+- Use `backticks` around variable names and inline code excerpts.
+
+- Use plain fences (```) around code blocks inside of pydocs.
+
+- For classes with many methods, use a concise docstring on the class that explains all
+  the common information, and avoid repeating the same information on every method.
+
+- Docstrings should provide context or as concisely as possible explain “why”, not
+  obvious details evident from the class names, function names, parameter names, and
+  type annotations.
+
+- Docstrings *should* mention any key rationale or pitfalls when using the class or
+  function.
+
+- Avoid obvious or repetitive docstrings.
+  Do NOT add pydocs that just repeat in English facts that are obvious from the function
+  name, variable name, or types.
+  That is silly and obvious and makes the code longer for no reason.
+
+- Do NOT list args and return values if they’re obvious.
+  In the above examples, you do not need and `Arguments:` or `Returns:` section, since
+  sections as it is obvious from context.
+  do list these if there are many arguments and their meaning isn’t clear.
+  If it returns a less obvious type like a tuple, do explain in the pydoc.
+
+- Exported/public variables, functions, or methods SHOULD have concise docstrings.
+  Internal/local variables, functions, and methods DO NOT need docstrings unless their
+  purpose is not obvious.
+
+## General Clean Coding Practices
+
+- Avoid writing trivial wrapper functions.
+  For example, when writing a class DO NOT blindly make delegation methods around public
+  member variables. DO NOT write methods like this:
+  ```python
+      def reassemble(self) -> str:
+        """Call the original reassemble method."""
+        return self.paragraph.reassemble()
+  ```
+  In general, the user can just call the enclosed objects methods, reducing code bloat.
+
+- If a function does not use a parameter, but it should still be present, you can use `#
+  pyright: ignore[reportUnusedParameter]` in a comment to suppress the linter warning.
+
+## Guidelines for Backward Compatibility
+
+- When changing code in a library or general function, if a change to an API or library
+  will break backward compatibility, MENTION THIS to the user.
+
+- DO NOT implement additional code for backward compatiblity (such as extra methods or
+  variable aliases or comments about backward compatibility) UNLESS the user has
+  confirmed that it is necessary.

python_package_folder-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+# This workflow will install Python dependencies, run tests and lint with a single version of Python
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: CI
+
+on:
+  push:
+    # Use ["main", "master"] for CI only on the default branch.
+    # Use ["**"] for CI on all branches.
+    branches: ["main", "master"]
+  pull_request:
+    branches: ["main", "master"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        # Update this as needed:
+        # Common platforms: ["ubuntu-latest", "macos-latest", "windows-latest"]
+        os: ["ubuntu-latest"]
+        python-version: ["3.11", "3.12", "3.13"]
+
+    # Linux only by default. Use ${{ matrix.os }} for other OSes.
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      # Generally following uv docs:
+      # https://docs.astral.sh/uv/guides/integration/github/
+
+      - name: Checkout (official GitHub action)
+        uses: actions/checkout@v4
+        with:
+          # Important for versioning plugins:
+          fetch-depth: 0
+
+      - name: Install uv (official Astral action)
+        uses: astral-sh/setup-uv@v5
+        with:
+          # Update this as needed:
+          version: "0.9.5"
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up Python (using uv)
+        run: uv python install
+
+      # Alternately can use the official Python action:
+      # - name: Set up Python (using actions/setup-python)
+      #   uses: actions/setup-python@v5
+      #   with:
+      #     python-version: ${{ matrix.python-version }}
+
+      - name: Install all dependencies
+        run: uv sync --all-extras
+
+      - name: Run linting
+        run: uv run python devtools/lint.py
+
+      - name: Run tests
+        run: uv run pytest

python_package_folder-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch: # Enable manual trigger.
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # Mandatory for OIDC.
+      contents: read
+    steps:
+      - name: Checkout (official GitHub action)
+        uses: actions/checkout@v4
+        with:
+          # Important for versioning plugins:
+          fetch-depth: 0
+
+      - name: Install uv (official Astral action)
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.9.5"
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Set up Python (using uv)
+        run: uv python install
+
+      - name: Install all dependencies
+        run: uv sync --all-extras
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always
+        # Although uv is newer and faster, the "official" publishing option is the one from PyPA,
+        # which uses twine. If desired, replace `uv publish` with:
+        # uses: pypa/gh-action-pypi-publish@release/v1

python_package_folder-0.1.0/.gitignore

@@ -0,0 +1,183 @@
+# Generated by Makefile
+CLAUDE.md
+AGENTS.md
+
+# Additions to standard GitHub .gitignore:
+*.bak
+*.orig
+tmp/
+trash/
+attic/
+.kash/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$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
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# 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
+.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/
+
+# PyPI configuration file
+.pypirc

python_package_folder-0.1.0/.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

python_package_folder-0.1.0/LICENSE

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