| Name | kochen JSON |
| Version |
0.2024.1
JSON |
| download |
| home_page | None |
| Summary | A compilation of boilerplate scribbles |
| upload_time | 2024-04-29 16:28:31 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
boilerplate
recipe
script
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Boilerplate library
Pain point: Repetitive coding of the same functionality, which often involves doing the same Google searches.
Really a list of recipes for consolidation.
Some workflows:
Run tests:
```
python -m pytest
```
Install library:
```
pip install -e .
```
Uninstall library:
```
python setup.py develop -u
```
## Design rationale
This is partly spurred by my usage of convenience scripts in the context of an experimental physics laboratory,
with the following usage observations:
**Problem**:
Scripts are commonly archived for reference, either for reuse or for referencing data collection strategies. Old scripts tend to break from outdated API.
* **Solution**: Ensure that the library is strongly back-compatible with old functionality,
not just via version-control, but every commit should be back-compatible.
* **Problem**: Functions that share the same name are essentially overridden
(no signature polymorphism).
* **Problem**: Functions being used may become opaque to the user, e.g. when using an IDE
which can perform static declaration lookups, dynamic assignment of functionality (especially under a different alias) can lead to difficulties in usage.
* **Anti-pattern**: Avoid declaring functions with different names to differentiate minute
behavioural changes. This can quickly pollute the library namespace.
* **Solution**: Stick to the same function names as much as possible, and clearly define
the function contract. Best if a static type checker is used to enforce contractual obligations. Where functions are likely deprecated, throw out one (and only one) warning during initial script invocation.
* **Possible solution**: Pre-compile currently used library into current directory, so that
library references change from global reference to local reference.
* **Problem**: Precompilation and duplication of libraries can lead to bloated software size
and excessive duplication in a version-controlled environment. This also makes usage of
updated libraries in an old environment difficult.
* **Possible solution**: Use of decorators to mark the version of certain functions.
This mark ought to be representative of the development order of the library, i.e. older
commits to the library should have older marks (perhaps a datetime). Individual scripts should keep track of which functions it should be calling, perhaps as a version pinning
comment if no such comment is initially detected.
Calling of newer functionality should still be supported, i.e. forward-compatibility.
* **Anti-pattern**: Marking of functions by shelving them within subdirectory corresponding
to their version number should be avoided. This poses issues when (1) cross-referencing
similar but competing implementations, (2) developer overhead from choosing directories.
**Problem**: Old scripts may have missing nested directory dependencies.
* **Solution**:
Package all required functionality in a single library. Where not possible, pull the
library functions into a version-control and/or a centralized environment.
* **Anti-pattern**: Functionality that are frequently updated and
cannot be reasonably maintained
(e.g. porting of `numpy` functions is not feasible long-term - will
eventually deviate from updated implementations) should be delegated to third-party libraries.
* **Anti-pattern**: Avoid deploying of library as a standalone
**Problem**: Older API may depend on older implementations of third-party libraries.
* **Anti-pattern**:
Developer could document which libraries the functions were written for, and
throw warnings when libraries invoked do not match those specified by function.
This however increases documentation overhead (grows with size of library),
and may not necessarily extend to later releases which may be compatible.
* **Possible solution**:
Provide suggestion of possible version conflict during a third-party library dependency call.
* **Problem**:
Wrong diagnosis can occur, e.g. errors due to buggy implementation of third-party functionality.
* **Solution**:
Not solved.
**Problem**: Scripts referencing libraries deployed in a central networked repository may
break when connection to said network is lost. Even more so for this glue library.
* **Solution**: Avoid performing `git clone ... && pip install -e .` workflows, especially
over a network. Where possible, enforce either `pip install git+...` or `pip install [PYPI]` workflows instead.
* **Possible solution**: For locally developed third-party dependencies, rely on virtual
file systems (that cache contents and update dynamically whenever a change is detected),
or prepare mirrors (i.e. defer to local library if central repository cannot be accessed).
Still a work-in-progress!
----
Some newer updates after a long lull on implementing the deprecation method.
Firstly, there seems to be some proposal [PEP723](https://peps.python.org/pep-0723/) floating around that are still provisional as of 2023-11-30 (looks like [PEP722](https://peps.python.org/pep-0722/) has been rejected in favor of PEP723). PEP723 suggests to have a following code block for embedding `pyproject.toml` in single-file scripts (arguably important for users who are not necesarily familiar with installing dependencies). Looks like this:
```python
# /// pyproject
# [run]
# requires-python = ">=3.11"
# dependencies = [
# "requests<3",
# "rich",
# ]
# ///
```
Note this does not actually fix the problem of having conflicting library versions. We want full backwards compatibility, as far as this library is concerned (hard to control versions on other dependencies, which is the whole point of trying to have this library self-contained).
Had a realization that library versioning should not be controlled by `git`, which limits applicability in cases where the library files are directly copied, or where `git` was not used to clone the repository in the first place. Need to somehow embed the version that is used by the script, hopefully automagically. This looks like a possible method: [Method 1](https://stackoverflow.com/questions/45684307/get-source-script-details-similar-to-inspect-getmembers-without-importing-the) and [Method 2](https://stackoverflow.com/questions/34491808/how-to-get-the-current-scripts-code-in-python) and [Method 3](https://stackoverflow.com/questions/427453/how-can-i-get-the-source-code-of-a-python-function).
Some goals:
* Backward compatibility only up till Py3.6, because the lab
Raw data
{
"_id": null,
"home_page": null,
"name": "kochen",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "boilerplate, recipe, script",
"author": null,
"author_email": "Justin Peh Yu Xiang <pehyuxiang@gmail.com>",
"download_url": null,
"platform": null,
"description": "# Boilerplate library\n\nPain point: Repetitive coding of the same functionality, which often involves doing the same Google searches.\nReally a list of recipes for consolidation.\n\nSome workflows:\n\nRun tests:\n\n```\npython -m pytest\n```\n\nInstall library:\n\n```\npip install -e .\n```\n\nUninstall library:\n\n```\npython setup.py develop -u\n```\n\n## Design rationale\n\nThis is partly spurred by my usage of convenience scripts in the context of an experimental physics laboratory,\nwith the following usage observations:\n\n**Problem**:\nScripts are commonly archived for reference, either for reuse or for referencing data collection strategies. Old scripts tend to break from outdated API.\n\n* **Solution**: Ensure that the library is strongly back-compatible with old functionality,\n not just via version-control, but every commit should be back-compatible.\n* **Problem**: Functions that share the same name are essentially overridden\n (no signature polymorphism).\n* **Problem**: Functions being used may become opaque to the user, e.g. when using an IDE\n which can perform static declaration lookups, dynamic assignment of functionality (especially under a different alias) can lead to difficulties in usage.\n* **Anti-pattern**: Avoid declaring functions with different names to differentiate minute\n behavioural changes. This can quickly pollute the library namespace.\n* **Solution**: Stick to the same function names as much as possible, and clearly define\n the function contract. Best if a static type checker is used to enforce contractual obligations. Where functions are likely deprecated, throw out one (and only one) warning during initial script invocation.\n* **Possible solution**: Pre-compile currently used library into current directory, so that\n library references change from global reference to local reference.\n* **Problem**: Precompilation and duplication of libraries can lead to bloated software size\n and excessive duplication in a version-controlled environment. This also makes usage of\n updated libraries in an old environment difficult.\n* **Possible solution**: Use of decorators to mark the version of certain functions.\n This mark ought to be representative of the development order of the library, i.e. older\n commits to the library should have older marks (perhaps a datetime). Individual scripts should keep track of which functions it should be calling, perhaps as a version pinning\n comment if no such comment is initially detected.\n Calling of newer functionality should still be supported, i.e. forward-compatibility.\n* **Anti-pattern**: Marking of functions by shelving them within subdirectory corresponding\n to their version number should be avoided. This poses issues when (1) cross-referencing\n similar but competing implementations, (2) developer overhead from choosing directories.\n\n**Problem**: Old scripts may have missing nested directory dependencies.\n\n* **Solution**:\n Package all required functionality in a single library. Where not possible, pull the\n library functions into a version-control and/or a centralized environment.\n* **Anti-pattern**: Functionality that are frequently updated and\n cannot be reasonably maintained\n (e.g. porting of `numpy` functions is not feasible long-term - will\n eventually deviate from updated implementations) should be delegated to third-party libraries.\n* **Anti-pattern**: Avoid deploying of library as a standalone\n\n**Problem**: Older API may depend on older implementations of third-party libraries.\n\n* **Anti-pattern**:\n Developer could document which libraries the functions were written for, and\n throw warnings when libraries invoked do not match those specified by function.\n This however increases documentation overhead (grows with size of library),\n and may not necessarily extend to later releases which may be compatible.\n* **Possible solution**:\n Provide suggestion of possible version conflict during a third-party library dependency call.\n* **Problem**:\n Wrong diagnosis can occur, e.g. errors due to buggy implementation of third-party functionality.\n* **Solution**:\n Not solved.\n\n**Problem**: Scripts referencing libraries deployed in a central networked repository may\n break when connection to said network is lost. Even more so for this glue library.\n\n* **Solution**: Avoid performing `git clone ... && pip install -e .` workflows, especially\n over a network. Where possible, enforce either `pip install git+...` or `pip install [PYPI]` workflows instead.\n* **Possible solution**: For locally developed third-party dependencies, rely on virtual\n file systems (that cache contents and update dynamically whenever a change is detected),\n or prepare mirrors (i.e. defer to local library if central repository cannot be accessed).\n\nStill a work-in-progress!\n\n----\n\nSome newer updates after a long lull on implementing the deprecation method.\nFirstly, there seems to be some proposal [PEP723](https://peps.python.org/pep-0723/) floating around that are still provisional as of 2023-11-30 (looks like [PEP722](https://peps.python.org/pep-0722/) has been rejected in favor of PEP723). PEP723 suggests to have a following code block for embedding `pyproject.toml` in single-file scripts (arguably important for users who are not necesarily familiar with installing dependencies). Looks like this:\n\n```python\n# /// pyproject\n# [run]\n# requires-python = \">=3.11\"\n# dependencies = [\n# \"requests<3\",\n# \"rich\",\n# ]\n# ///\n```\n\nNote this does not actually fix the problem of having conflicting library versions. We want full backwards compatibility, as far as this library is concerned (hard to control versions on other dependencies, which is the whole point of trying to have this library self-contained).\n\nHad a realization that library versioning should not be controlled by `git`, which limits applicability in cases where the library files are directly copied, or where `git` was not used to clone the repository in the first place. Need to somehow embed the version that is used by the script, hopefully automagically. This looks like a possible method: [Method 1](https://stackoverflow.com/questions/45684307/get-source-script-details-similar-to-inspect-getmembers-without-importing-the) and [Method 2](https://stackoverflow.com/questions/34491808/how-to-get-the-current-scripts-code-in-python) and [Method 3](https://stackoverflow.com/questions/427453/how-can-i-get-the-source-code-of-a-python-function).\n\nSome goals:\n\n* Backward compatibility only up till Py3.6, because the lab",
"bugtrack_url": null,
"license": null,
"summary": "A compilation of boilerplate scribbles",
"version": "0.2024.1",
"project_urls": null,
"split_keywords": [
"boilerplate",
" recipe",
" script"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "024c9366671835bbe01e4b19e32f8bc4daabf73895174965e71e1f076905ef8d",
"md5": "ae4a18466227a1df243f7b830d9255eb",
"sha256": "9f2767fe06e7d78f5df1b90c322655083002528d1a325ceee7aa8667e113d37a"
},
"downloads": -1,
"filename": "kochen-0.2024.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ae4a18466227a1df243f7b830d9255eb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 49912,
"upload_time": "2024-04-29T16:28:31",
"upload_time_iso_8601": "2024-04-29T16:28:31.512769Z",
"url": "https://files.pythonhosted.org/packages/02/4c/9366671835bbe01e4b19e32f8bc4daabf73895174965e71e1f076905ef8d/kochen-0.2024.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-29 16:28:31",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "kochen"
}
