From 44f2d1722a05c6077934a6326ef616cb3b4fb9e0 Mon Sep 17 00:00:00 2001 From: BJ Dierkes Date: Sun, 10 Nov 2024 01:00:57 -0600 Subject: [PATCH] Add Notes for Windows/macOS Targeted Development --- README.md | 121 ++++++++++++++++++++++------------ pdm.lock | 11 +++- tests/core/test_foundation.py | 2 +- 3 files changed, 88 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index e8d4cc13..012f18f1 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,19 @@ Cement is an advanced Application Framework for Python, with a primary focus on The first commit to Git was on Dec 4, 2009. Since then, the framework has seen several iterations in design, and has continued to grow and improve since it's inception. Cement is the most stable, and complete framework for command line and backend application development. +## Installation + +``` +pip install cement +``` + +Optional CLI Extras (for development): + +``` +pip install cement[cli] +``` + + ## Core Features Cement core features include (but are not limited to): @@ -26,10 +39,12 @@ Cement core features include (but are not limited to): - Hook support adds a bit of magic to apps and also ties into framework - Zero external dependencies* (not including optional extensions) - 100% test coverage (`pytest`, `coverage`) -- 100% PEP8 compliant (`ruff`) +- 100% PEP8 compliance (`ruff`) +- Type annotation compliance (`mypy`) - Extensive API Reference (`sphinx`) - Tested on Python 3.8+ + ## Optional Extensions Some extensions that are shipped with the mainline Cement source do require external dependencies. It is the responsibility of the application developer to include these dependencies along with their application, as Cement explicitly does not include them. Dependencies can be installed via each extensions optional package (ex: `cement[colorlog]`, `cement[redis]`, etc). @@ -50,11 +65,12 @@ See: [https://docs.builtoncement.com/extensions](https://docs.builtoncement.com/ The Cement CLI Application Framework is Open Source and is distributed under the BSD License (three clause). Please see the LICENSE file included with this software. + ## Development ### Docker -This project includes a `docker-compose` configuration that sets up all required services, and dependencies for development and testing. This is the recommended path for local development, and is the only fully supported option. +This project includes a Docker Compose configuration that sets up all required services, and dependencies for development and testing. This is the recommended path for local development, and is the only fully supported option. The following creates all required docker containers, and launches an BASH shell within the `cement` dev container for development. ``` @@ -66,9 +82,9 @@ $ make dev The above is the equivalent of running: ``` -$ docker-compose up -d +$ docker compose up -d -$ docker-compose exec cement /bin/bash +$ docker compose exec cement /bin/bash ``` All execution is done *inside the docker containers*. @@ -98,62 +114,81 @@ $ docker-compose exec cement-py39 /bin/bash ``` -### Vagrant +### Windows Targeted Development -An alternative option is included to run Vagrant for development. This is partially supported, primarily for the purpose of developing/testing on Windows as well as testing specific issues on target operating systems. +*Windows development and support is not 100% complete. Applications Built on Cement is known to run and work on Windows well, however it is not a primary target for development and as such the setup is not as streamlined and currently has several known issues.* -To see a list of configured systems: +If you are developing on Windows, the recommended path is still Docker. However if you are specifically targeting development *for* Windows you will want to run Python/Cement natively which will require setting up a development environment on the Windows host. + +This is very rough (future doc coming), however the following will be required: + +- Python 3.x (latest stable preferred) + - pip + - pipx + - pdm +- Visual C++ 14.0 or Greater Build Tools + - Including: CMake + +Assuming Python/PIP are installed, the following will install PDM: ``` -$ vagrant status +pip install pipx + +pipx install pdm ``` -#### Linux +C++ Build Tools are install, the following will create a development virtual env: ``` -$ vagrant up linux +pdm venv create -$ vagrant ssh linux - -vagrant@linux $ cd /vagrant - -vagrant@linux $ bash scripts/vagrant/bootstrap.sh - -vagrant@linux $ make virtualenv - -vagrant@linux $ pdm venv activate - -|> cement >| $ +pdm install --without memcached ``` -#### Windows - -*Windows development and support is not 100% complete. Cement is known to run and work on Windows, however it is not a primary target for development and as such the setup is not as streamlined and currently has several known errors.* - -The following assumes you're running these two initial commands from a unix based system: +You can then run the core tests: ``` -$ make clean - -$ vagrant up windows -``` - -RDP or Login to Desktop/Console, and open a PowerShell terminal: - -``` -C:\> cd C:\Vagrant - -C:\Vagrant> powershell.exe scripts\vagrant\bootstrap.ps1 - -C:\Vagrant> make virtualenv - -C:\Vagrant> pdm venv activate - -C:\Vagrant> make test-core +pdm run pytest --cov=cement.core tests/core ``` *Note that only the core library is fully tested on Windows.* +Please explore the Makefile for helpers that may or may not work. Example, the following will run the same as the above `pdm run pytest` command: + +``` +make test-core +``` + +And, you can run Cement CLI via: + +``` +pdm run cement --help +``` + + +### macOS Targeted Development + +Similar to the above... if you are developing on macOS, the recommended path is still Docker. However if you are specifically targeting development *for* macOS you will want to run Python/Cement natively which will require setting up a development environment on the macOS host. + +This is less nuanced than Windows, however still required some dependencies that will not be fully covered here (example: memcached). The following will get you setup to run the core library tests. + +``` +pip install pipx + +pipx install pdm + +pdm venv create + +pdm install --without memcached + +make test-core +``` + +And, you can run Cement CLI via: + +``` +pdm run cement --help +``` ### Running Tests and Compliance diff --git a/pdm.lock b/pdm.lock index 40259a27..5bff9c53 100644 --- a/pdm.lock +++ b/pdm.lock @@ -4,8 +4,11 @@ [metadata] groups = ["default", "alarm", "argparse", "cli", "colorlog", "configparser", "daemon", "dev", "docs", "dummy", "generate", "jinja2", "json", "logging", "memcached", "mustache", "plugin", "print", "redis", "scrub", "smtp", "tabulate", "watchdog", "yaml"] strategy = ["cross_platform", "inherit_metadata"] -lock_version = "4.4.1" -content_hash = "sha256:93bbcbfd6b1a08c9a37b42a42d1300b6f9ede3eb6e643a085a8152fb81a60d88" +lock_version = "4.5.0" +content_hash = "sha256:7837e4994dfec4e6dc58ed6160458ce67c146f206cca44eceef966cae3293b18" + +[[metadata.targets]] +requires_python = ">=3.8" [[package]] name = "alabaster" @@ -25,6 +28,9 @@ requires_python = ">=3.7" summary = "Timeout context manager for asyncio programs" groups = ["redis"] marker = "python_full_version < \"3.11.3\"" +dependencies = [ + "typing-extensions>=3.6.5; python_version < \"3.8\"", +] files = [ {file = "async-timeout-4.0.3.tar.gz", hash = "sha256:4640d96be84d82d02ed59ea2b7105a0f7b33abe8703703cd0ab0bf87c427522f"}, {file = "async_timeout-4.0.3-py3-none-any.whl", hash = "sha256:7405140ff1230c310e51dc27b3145b9092d659ce68ff733fb0cefe3ee42be028"}, @@ -399,6 +405,7 @@ summary = "Read metadata from Python packages" groups = ["docs", "mustache"] marker = "python_version < \"3.10\"" dependencies = [ + "typing-extensions>=3.6.4; python_version < \"3.8\"", "zipp>=0.5", ] files = [ diff --git a/tests/core/test_foundation.py b/tests/core/test_foundation.py index 2dd8b5d7..53c19a35 100644 --- a/tests/core/test_foundation.py +++ b/tests/core/test_foundation.py @@ -103,7 +103,7 @@ def test_basic(): def test_loaded_extensions(): - if platform.system().lower() in ['windows']: + if platform.system().lower() in ['windows', 'darwin']: ext_list = [ 'colorlog', 'dummy',