cgse 2025.0.2__tar.gz → 2025.0.3__tar.gz

{cgse-2025.0.2 → cgse-2025.0.3}/.gitignore

@@ -30,6 +30,10 @@ venv
 
 .idea
 
+# MKDOCS documentation site
+
+/site
+
 # Packaging
 
 uv.lock

{cgse-2025.0.2 → cgse-2025.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cgse
-Version: 2025.0.2
+Version: 2025.0.3
 Summary: Generic Common-EGSE: Commanding and monitoring lab equipment
 Author-email: Rik Huygen <rik.huygen@kuleuven.be>, Sara Regibo <sara.regibo@kuleuven.be>
 License: MIT

cgse-2025.0.3/docs/custom_theme/main.html

@@ -0,0 +1,54 @@
+{% extends "base.html" %}
+
+{% block extrahead %}
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/firacode/6.2.0/fira_code.min.css" integrity="sha512-MbysAYimH1hH2xYzkkMHB6MqxBqfP0megxsCLknbYqHVwXTCg9IqHbk+ZP/vnhO8UEW6PaXAkKe2vQ+SWACxxA==" crossorigin="anonymous" referrerpolicy="no-referrer" />
+<!-- Fathom - beautiful, simple website analytics -->
+<script src="https://cdn.usefathom.com/script.js" data-site="TAUKXRLQ" defer></script>
+<!-- / Fathom -->
+
+
+<meta name="twitter:card" content="summary">
+<meta name="twitter:site" content="@textualizeio">
+<meta name="twitter:creator" content="@willmcgugan">
+<meta property="og:title" content="Textual - {{ page.title }}">
+<meta property="og:type" content="article">
+<meta property="og:url" content="{{ page.canonical_url | url }}">
+<meta property="og:site_name" content="Textual Documentation">
+<meta property="og:description" content="Textual is a TUI framework for Python, inspired by modern web development.">
+<meta property="og:image" content="https://raw.githubusercontent.com/Textualize/textual/main/imgs/textual.png">
+
+<style>
+
+    @font-face {
+        font-family: "Virgil";
+        src: url("https://unpkg.com/@excalidraw/excalidraw@0.12.0/dist/excalidraw-assets/Virgil.woff2");
+      }
+      @font-face {
+        font-family: "Cascadia";
+        src: url("https://unpkg.com/@excalidraw/excalidraw@0.12.0/dist/excalidraw-assets/Cascadia.woff2");
+      }
+
+
+
+</style>
+
+<script lang="js">
+window.onload = async (event) => {
+  const demos = document.querySelectorAll(".textual-web-demo");
+
+  if (demos.length){
+    await fetch("https://textual-web-demos.fly.dev/health-check/", {
+      method: 'GET',
+      mode: 'no-cors'
+    });
+    demos.forEach((element)=>{
+      const app = element.dataset.app;
+      const iframe_html = `<div class="textual-web-demo"><iframe width="100%" onload="this.parentElement.classList.add('-loaded');" src="https://textual-web.io/textualize/${app}?delay=y&fontsize=12&ping=https://textual-web-demos.fly.dev/health-check/"></iframe></div>`;
+      element.outerHTML = iframe_html;
+    });
+  }
+}
+
+</script>
+
+{% endblock %}

cgse-2025.0.3/docs/dev_guide/coding_style.md

@@ -0,0 +1,95 @@
+# Style Guide
+
+This part of the developer guide contains instructions for coding styles that are adopted for this project.
+
+The style guide that we use for this project is [PEP8](https://www.python.org/dev/peps/pep-0008/). This is the standard for Python code and all IDEs, parsers and code formatters understand and work with this standard. PEP8 leaves room for project specific styles. A good style guide that we can follow is the [Google Style Guide](https://google.github.io/styleguide/pyguide.html).
+
+The following sections will give the most used conventions with a few examples of good and bad.
+
+## TL;DR
+
+| Type | Style | Example |
+|------|-------|---------|
+| Classes | CapWords | ProcessManager, ImageViewer, CommandList, Observation, MetaData |
+| Methods & Functions | lowercase with underscores | get_value, set_mask, create_image |
+| Variables | lowercase with underscores | key, last_value, model, index, user_info |
+| Constants | UPPERCASE with underscores | MAX_LINES, BLACK, COMMANDING_PORT |
+| Modules & packages | lowercase **no** underscores | dataset, commanding, multiprocessing |
+
+## General
+
+* Name the class or variable or function with what it is, what it does or what it contains. A variable named `user_list` might look good at first, but what if at some point you want to change the list to a set so it can not contain duplicates. Are you going to rename everything into `user_set` or would `user_info` be a better name?
+* Never use dashes in any name, they will raise a `SyntaxError: invalid syntax`.
+* We introduce a number of relaxations to not break backward compatibility for the sake of a naming convention. As described in [A Foolish Consistency is the Hobgoblin of Little Minds](https://legacy.python.org/dev/peps/pep-0008/#a-foolish-consistency-is-the-hobgoblin-of-little-minds): _Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is the most important. [...] do not break backwards compatibility just to comply with this PEP!_
+
+## Classes
+
+Always use CamelCase (Python uses CapWords) for class names. When using acronyms, keep them all UPPER case.
+
+* Class names should be nouns, like Observation
+* Make sure to name classes distinctively
+* Stick to one word for a concept when naming classes, i.e. words like `Manager` or `Controller` or `Organizer` all mean similar things. Choose one word for the concept and stick to it.
+* If a word is already part of a package or module, don't use the same word in the class name again.
+
+Good names are: `Observation`, `CalibrationFile`, `MetaData`, `Message`, `ReferenceFrame`, `URLParser`.
+
+## Methods and Functions
+
+A function or a method does something (and should only do one thing, SRP=Single Responsibility Principle), it is an action, so the name should reflect that action.
+
+Always use lowercase words separated with underscores.
+
+Good names are: `get_time_in_ms()`, `get_commanding_port()`, `is_connected()`, `parse_time()`, `setup_mask()`.
+
+When working with legacy code or code from another project, names may be in camelCase (with the first letter a lower case letter). So we can in this case use also `getCommandPort()` or `isConnected()` as method and function names.
+
+## Variables
+
+Use the same naming convention as functions and methods, i.e. lowercase with underscores.
+
+Good names are: `key`, `value`, `user_info`, `model`, `last_value`
+
+Bad names: `NSegments`, `outNoise`
+
+Take care not to use builtins: `list`, `type`, `filter`, `lambda`, `map`, `dict`, ...
+
+Private variables (for classes) start with an underscore: `_name` or `_total_n_args`.
+
+In the same spirit as method and function names, the variables can also be in camelCase for specific cases.
+
+## CONSTANTS
+
+Use ALL_UPPER_CASE with underscores for constants. Use constants always within a name space, not globally.
+
+Good names: `MAX_LINES`, `BLACK`, `YELLOW`, `ESL_LINK_MODE_DISABLED`
+
+## Modules and Packages
+
+Use simple words for modules, preferably just one word like `datasets` or `commanding` or `storage` or `extensions`. If two words are unavoidable, just concatenate them, like `multiprocessing` or `sampledata` or `testdata`. If needed for readability, use an underscore to separate the words, e.g. `image_analysis`.
+
+## Import Statements
+
+* Group and sort import statements
+* Never use the form `from <module> import *`
+* Always use absolute imports in scripts
+
+Be careful that you do not name any modules the same as a module in the Python standard library. This can result in strange effects and may result in an `AttributeError`. Suppose you have named a module `math` in the `egse` directory and it is imported and used further in the code as follows:
+
+```python
+from egse import math
+
+# in some expression further down the code you might use
+
+math.exp(a)
+```
+
+This will result in the following runtime error:
+
+```text
+File "some_module.py", line 8, in <module>
+  print(math.exp(a))
+AttributeError: module 'egse.math' has no attribute 'exp'
+```
+
+Of course this is an obvious example, but it might be more obscure like e.g. in this [GitHub issue](https://github.com/ParmEd/ParmEd/issues/148): 'module' 
+object has no attribute 'Cmd'.

cgse-2025.0.3/docs/dev_guide/docs.md

@@ -0,0 +1,53 @@
+
+# Building the documentation
+
+- Make sure you are in a virtual environment with Python 3.10+
+- Run the `mkdocs serve` from the project root older
+- Create new pages by adding folder and Markdown files inside `docs/*`
+
+## Set up your environment
+
+I created a virtual environment using `pyenv` and when I'm working on the documentation, I start up a shell with 
+this environment. Currently, only `mkdocs` and `mkdocs-material` are needed. Of course, you need to install these 
+only once.
+
+```shell
+$ pyenv virtualenv 3.10 cgse-doc-3.10
+$ pyenv shell cgse-doc-3.10
+$ pip install --upgrade pip setuptools wheel
+$ pip install mkdocs
+$ pip install mkdocs-material
+```
+
+From this shell, navigate to the project root folder and start the _live-reload_ server of `mkdocs`.
+
+```shell
+$ cd ~/github/cgse
+$ mkdocs serve
+```
+
+Now you can update files, create new folders in `docs/*`, create new Markdown files and all changes will be reloaded 
+live in the browser.
+
+When you are ready with updating, you will need to build the site and publish it on GitHub pages:
+
+```shell
+$ mkdocs build
+$ mkdocs gh-deploy -r upstream -m "documentation update on .."
+```
+
+## Commands
+
+- `mkdocs serve` — start the live-reloading docs server
+- `mkdocs build` — build the documentation site
+- `mkdocs deploy` — publish your documentation on GitHub pages
+- `mkdocs -h` — print a help message for more options
+
+## Project layout
+
+```text
+mkdocs.yml     # the mkdocs configuration file
+docs/
+    index.md   # the documentation homepage
+    ...        # other markdown pages, image, folders, ...
+```

cgse-2025.0.3/docs/dev_guide/index.md

@@ -0,0 +1,3 @@
+# Developer Guide
+
+Welcome to the CGSE developer guide! An in-depth reference on how to contribute to the CGSE.

cgse-2025.0.3/docs/dev_guide/installation.md

@@ -0,0 +1,2 @@
+
+# Installation Guide for Developers

cgse-2025.0.3/docs/dev_guide/uv.md

@@ -0,0 +1,131 @@
+
+# Working with `uv`
+
+`uv` is an extremely fast Python package and project manager, written in Rust. We will use `uv` as the single tool that replaces `pip`, `virtualenv`, `pyenv`, and more. The main tasks for which we will use `uv` are:
+
+- run and install Python versions
+- installing and managing a virtual environment
+- build all the packages in the workspace or monorepo
+- publish all the packages to PyPI
+- run scripts and apps
+
+## Installing `uv`
+
+On macOS and Linux you can install `uv` using `curl`:
+
+```shell
+$ curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+If you need more specific information on installing and upgrading `uv`, please refer to the [official documentation](https://docs.astral.sh/uv/getting-started/installation/).
+
+
+## Installing a Python version
+
+The CGSE is guaranteed to work with Python 3.9.x. We will gradually include higher versions of Python, but currently 
+these have not been tested. So, we will for the moment stick with Python 3.9.20. Install this version as follows:
+
+```shell
+$ uv python install 3.9.20
+```
+
+!!! note "`pyenv`"
+
+    When using `pyenv` to manage your Python versions, make sure you also have the same Python version installed 
+    with `pyenv` and `uv`. Otherwise you will run into the following error. This is a known issue with `uv`.
+
+    ```
+    pyenv: version `3.9.20' is not installed (set by /Users/rik/github/cgse/libs/cgse-common/.python-version)
+    ```
+
+You can check which Python versions are installed already on your system:
+
+```shell
+$ uv python list --only-installed
+cpython-3.12.8-macos-aarch64-none     /Users/rik/Library/Application Support/uv/python/cpython-3.12.8-macos-aarch64-none/bin/python3.12
+cpython-3.10.16-macos-aarch64-none    /Users/rik/Library/Application Support/uv/python/cpython-3.10.16-macos-aarch64-none/bin/python3.10
+cpython-3.9.21-macos-aarch64-none     /Users/rik/Library/Application Support/uv/python/cpython-3.9.21-macos-aarch64-none/bin/python3.9
+cpython-3.9.20-macos-aarch64-none     /Users/rik/Library/Application Support/uv/python/cpython-3.9.20-macos-aarch64-none/bin/python3.9
+cpython-3.9.6-macos-aarch64-none      /Library/Developer/CommandLineTools/usr/bin/python3 -> ../../Library/Frameworks/Python3.framework/Versions/3.9/bin/python3
+cpython-3.8.17-macos-aarch64-none     /Users/rik/Library/Application Support/uv/python/cpython-3.8.17-macos-aarch64-none/bin/python3.8
+```
+
+## Create a virtual environment
+
+!!! info inline end "Pin a Python version"
+
+    You can pin a python version with the command:
+
+    ```
+    $ uv python pin 3.9.20
+    ```
+
+    `uv` will search for a pinned version in the parent folders up to the root folder or your home directory.
+
+
+You can create a virtual environment with `uv` for the specific Python version as follows. The '`--python`' is optional 
+and `uv` will use the default (pinned) Python version when creating a `venv` without this option. When creating a 
+virtual environment make sure you are in the package root, e.g. `~/github/cgse/libs/cgse-common`.
+
+```shell
+$ cd ~/github/cgse/libs/cgse-common
+$ uv venv --python 3.9.20
+```
+
+Assuming you are in the package root where you created the virtual environment, you can now install its dependencies 
+with `pip install` as follows:
+
+```shell
+$ uv pip install -r pyproject.toml
+```
+
+To install the current project as an editable package:
+
+```shell
+$ uv pip install -e .
+```
+
+!!! note 
+
+    If you don't want to use the `uv` commands, you can activate the virtual environment and use the original `pip` 
+    and `python` commands as you are used to.
+
+    ```
+    $ source .venv/bin/activate
+    ```
+
+## Building and publishing all packages
+
+We have chosen for one and the same version number for all packages in the `cgse` monorepo. That means that whenever 
+we make a change to one of the packages and want to release that change, all packages shall be rebuild and published.
+
+!!! inline end warning
+
+    When working in a workspace, keep in mind that the commands `uv run` and `uv sync` by default work on the 
+    workspace root. That means that when you run the `uv run pip install <package>` command, the `.venv` at the 
+    workspace root will be updated or created if it didn't exist. Similar for the `uv sync` command, there is only 
+    one `uv.lock` file at the root of the workspace.  
+
+Fortunately, with `uv`, that is done in a few commands.
+
+When you are in the monorepo root folder, you can build all packages at once. They will be placed in the `dist` folder 
+of the root package. Before building, make sure you update the version in the `pyproject.toml` of the root package 
+and then bump the versions. Before building, clean up the `dist` folder, then you can do a default `uv publish` afterwards.
+
+```shell
+$ cd <monorepo root>
+$ uv run bump.py
+$ rm -r dist
+$ uv build --all-packages
+```
+
+Publish all packages in the root dist folder to PyPI. The UV_PUBLISH_TOKEN can be defined in a (read protected) ~/.
+setenv.bash file:
+
+```shell
+$ uv publish --token $UV_PUBLISH_TOKEN
+```
+
+The above command will publish all package to PyPI. If you don't want the token to be in a shell variable, you can 
+omit the `--token` in the command above. You will then be asked for a username, use `__token__` as the username and 
+then provide the token as a password.

cgse-2025.0.3/docs/getting_started.md

@@ -0,0 +1,6 @@
+All you need to get started using and building the CGSE.
+
+## Requirements
+
+- Python 3.9.x (we do not yet support higher versions, but are working to extend the list)
+- macOS or Linux

cgse-2025.0.3/docs/help.md

@@ -0,0 +1,9 @@
+
+# Help
+
+The best way to get help for something that you couldn't find in the documentation on this site, is to contact one of 
+the authors.
+
+## Bugs and Feature requests
+
+Report any bugs or issues through GitHub on the [CGSE issues](https://github.com/IvS-KULeuven/cgse/issues) page.