Release 0.1.0

.vscode/settings.json

@@ -0,0 +1,18 @@
+{
+    "editor.formatOnPaste": true,
+    "editor.formatOnSave": true,
+    "editor.formatOnType": true,
+    "editor.codeActionsOnSave": {
+        "source.organizeImports": true,
+        "source.fixAll": true
+    },
+    "[python]": {
+        "editor.defaultFormatter": "ms-python.black-formatter"
+    },
+    "python.defaultInterpreterPath": "${workspaceRoot}/.venv/bin/python",
+    "python.terminal.focusAfterLaunch": true,
+    "python.testing.unittestEnabled": true,
+    "python.analysis.autoFormatStrings": true,
+    "python.analysis.autoImportCompletions": true,
+    "autoDocstring.startOnNewLine": true
+}

CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2023-09-05
+
+### Added
+
+-   Helpers around file paths.

README.md

@@ -1,2 +1,204 @@
 # py-toolbox
-A set of utilities for Python projects
+
+`py-toolbox` is a set of utilities for Python projects
+
+<!-- vscode-markdown-toc -->
+
+-   [Requirements](#Requirements)
+-   [Installation](#Installation)
+-   [Development](#Development)
+    -   [Code style](#Codestyle)
+    -   [Testing](#Testing)
+-   [License](#License)
+
+<!-- vscode-markdown-toc-config
+	numbering=false
+	autoSave=true
+	/vscode-markdown-toc-config -->
+<!-- /vscode-markdown-toc -->
+
+## <a name='Requirements'></a>Requirements
+
+The toolbox has been written in **`Python 3`**, and it needs version `3.7`.
+
+The dependencies are managed by `pip` using the file `requirements.txt`.
+
+## <a name='Installation'></a>Installation
+
+To add `py-toolbox` to your project, run the following command:
+
+```sh
+pip install git+https://github.com/jsconan/py-toolbox.git
+```
+
+## Usage
+
+`py-toolbox` offers several utilities per domain.
+
+### Files
+
+The package `toolbox.files` offers file related utilities.
+
+-   `create_file_path(path: str) -> bool`:
+
+    Creates the parent path for a file.
+
+    **Note:** exceptions are caught internally, the function will always
+    return either with `True` in case of success, or `False` otherwise.
+
+    Args:
+
+    -   path (`str`): The path to the file.
+
+    Returns:
+
+    -   `bool`: `True` if the path has been created, `False` otherwise.
+
+    ***
+
+-   `delete_path(path: str) -> bool`:
+
+    Deletes the file or the folder at the given path.
+
+    If this is a folder, it must be empty.
+
+    **Note:** exceptions are caught internally, the function will always
+    return either with `True` in case of success, or `False` otherwise.
+
+    Args:
+
+    -   path (`str`): The path to the file or folder to delete.
+
+    Returns:
+
+    -   `bool`: `True` if the path has been deleted, `False` otherwise.
+
+    ***
+
+-   `get_application_name() -> str`:
+
+    Gets the name of the application, based on the root folder.
+
+    Returns:
+
+    -   `str`: The name of the application.
+
+    ***
+
+-   `get_application_path() -> PurePath`:
+
+    Gets the path to the application's root.
+
+    Returns:
+
+    -   `PurePath`: The path to the application's root.
+
+    ***
+
+-   `get_file_path(relative) -> PurePath`:
+
+    Gets a full path for a file inside the application.
+
+    Args:
+
+    -   relative (`str`): The internal path the file from the application's root.
+
+    Returns:
+
+    -   `PurePath`: The full path.
+
+    ***
+
+-   `get_module_folder_path(name: str) -> PurePath()`:
+
+    Gets the path to the folder containing the given module.
+
+    Args:
+
+    -   name (`str`): The module for which get the path.
+
+    Returns:
+
+    -   `PurePath`|`None`: The path to the folder containing the given module.
+
+    ***
+
+-   `get_module_path(name: str) -> PurePath()`:
+
+    Gets the path to the given module.
+
+    Args:
+
+    -   name (`str`): The module for which get the path.
+
+    Returns:
+
+    -   `PurePath`: The path to the module.
+
+    ***
+
+## <a name='Development'></a>Development
+
+Check out the repository:
+
+```sh
+git clone git@github.com:jsconan/py-toolbox.git
+```
+
+Then, create the virtual env and install the dependencies:
+
+```sh
+cd py-toolbox
+python3 -m venv ".venv"
+source "./venv/bin/activate"
+pip install -r requirements.txt
+```
+
+**Note:** For deactivating the virtual env, call the command `deactivate`.
+
+**Automating the environment activation/deactivation**
+
+For activating the virtual env automatically when entering the project folder, and deactivating it when leaving the folder, you can add this snippet to you shell profile:
+
+```sh
+cd() {
+    builtin cd "$@"
+
+    local venv=".venv"
+
+    # If a Python virtualenv is active, deactivate it if the new folder is outside
+    if [[ -v VIRTUAL_ENV ]] ; then
+        local parent=$(dirname "${VIRTUAL_ENV}")
+        if [[ "${PWD}"/ != "${parent}"/* ]] ; then
+            deactivate
+        fi
+    fi
+
+    # If a Python env folder is found then activate the virtualenv
+    if [[ -d "./${venv}" ]] ; then
+        # Is it a Python venv?
+        if [[ -f "./${venv}/bin/activate" ]] ; then
+            source "./${venv}/bin/activate"
+        fi
+    fi
+}
+```
+
+### <a name='Codestyle'></a>Code style
+
+Code is linted using PyLint and formatted using Black.
+
+### <a name='Testing'></a>Testing
+
+Each module comes with unit tests, by convention, a `test` folder must be added to each package
+
+Unit tests are made using `unittest`. To run them:
+
+```sh
+python3 -m unittest
+```
+
+## <a name='License'></a>License
+
+Copyright (c) 2023 Jean-Sébastien CONAN
+Distributed under the MIT License (See LICENSE file or copy at [http://opensource.org/licenses/MIT](http://opensource.org/licenses/MIT)).

pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "py-toolbox"
+version = "0.1.0"
+authors = [{ name = "Jean-Sébastien CONAN", email = "jsconan@gmail.com" }]
+description = "A set of utilities for Python projects"
+readme = "README.md"
+requires-python = ">=3.7"
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/jsconan/py-toolbox"
+"Bug Tracker" = "https://github.com/jsconan/py-toolbox/issues"

requirements.txt

@@ -0,0 +1,9 @@
+astroid==2.15.6
+dill==0.3.7
+isort==5.12.0
+lazy-object-proxy==1.9.0
+mccabe==0.7.0
+platformdirs==3.10.0
+pylint==2.17.5
+tomlkit==0.12.1
+wrapt==1.15.0

toolbox/files/__init__.py

@@ -0,0 +1,12 @@
+"""
+Entry point for the `files` package.
+"""
+from toolbox.files.path import (
+    create_file_path,
+    delete_path,
+    get_application_name,
+    get_application_path,
+    get_file_path,
+    get_module_folder_path,
+    get_module_path,
+)