| Name | aa-package-monitor JSON |
| Version |
2.0.0
JSON |
| download |
| home_page | None |
| Summary | An app that helps keep track of installed packages |
| upload_time | 2024-09-06 14:27:14 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Package Monitor
An app for keeping track of installed packages and outstanding updates with Alliance Auth.
[](https://pypi.org/project/aa-package-monitor/)
[](https://pypi.org/project/aa-package-monitor/)
[](https://pypi.org/project/aa-package-monitor/)
[](https://gitlab.com/ErikKalkoken/aa-package-monitor/-/pipelines)
[](https://codecov.io/gl/ErikKalkoken/aa-package-monitor)
[](https://gitlab.com/ErikKalkoken/aa-package-monitor/-/blob/master/LICENSE)
[](https://github.com/pre-commit/pre-commit)
[](https://github.com/psf/black)
[](https://discord.gg/zmh52wnfvM)
## Contents
- [Overview](#overview)
- [Screenshots](#screenshots)
- [Installation](#installation)
- [Updating](#updating)
- [User Guide](#user-guide)
- [Settings](#settings)
- [Permissions](#permissions)
- [Management Commands](#management-commands)
- [Change Log](CHANGELOG.md)
## Overview
Package Monitor is an app for Alliance Auth that helps you keep your installation up-to-date. It shows you all installed distributions packages and will automatically notify you, when there are updates available.
Features:
- Shows list of installed distributions packages with related Django apps (if any)
- Identifies new valid releases for installed packages on PyPI
- Notifies user which installed packages are outdated and should be updated
- Shows the number of outdated packages as badge in the sidebar
- Takes into account the requirements of all installed packages and the current Python version when recommending updates
- Option to add distribution pages to the monitor which are not related to Django apps
- Option to show all known distribution packages (as opposed to only the ones that belong to installed Django apps)
- Copy the respective command for a package update to your clipboard directly from the package list
- Can automatically notify admins when there is an update available for a currently installed package
- Supported languages: English :us:, German :de: and Russian :ru:
>**Hint**: Update notifications are sent as AA notifications to all admins. We recommend using [Discord Notify](https://gitlab.com/ErikKalkoken/aa-discordnotify) to automatically forward those notifications to Discord as DMs.
## Screenshots
## Installation
### Step 1 - Check Preconditions
Please make sure you meet all preconditions before proceeding:
- Package Monitor is a plugin for [Alliance Auth](https://gitlab.com/allianceauth/allianceauth). If you don't have Alliance Auth running already, please install it first before proceeding. (see the official [AA installation guide](https://allianceauth.readthedocs.io/en/latest/installation/auth/allianceauth/) for details)
### Step 2 - Install app
Make sure you are in the virtual environment (venv) of your Alliance Auth installation. Then install the newest release from PYPI:
```bash
pip install aa-package-monitor
```
### Step 3 - Configure settings
Add `'package_monitor'` to `INSTALLED_APPS`.
Add the following lines to your `local.py` to enable regular checking for updates:
```Python
CELERYBEAT_SCHEDULE['package_monitor_update_distributions'] = {
'task': 'package_monitor.tasks.update_distributions',
'schedule': crontab(minute='*/60'),
}
```
Finally, please also take a moment to consider how often you want to receive update notifications. The default is immediate, but you can also chose to receive notifications after a timeout, e.g. only once per 24 hours or once per week. If you choose a timeout you can also choose to get repeated notifications about the same updates, like a reminder. For more details please see the [Settings](#settings).
### Step 4 - Finalize installation
Run migrations & copy static files
```bash
python manage.py migrate
python manage.py collectstatic
```
Restart your supervisor services for Auth
### Step 5 - Initial data load
Last, but not least perform an initial data load of all distribution packages by running the following command:
```bash
python manage.py package_monitor_refresh
```
## Updating
```bash
pip install -U aa-package-monitor
python manage.py collectstatic
python manage.py migrate
```
Finally restart your AA supervisor services.
## User Guide
This section explains how to use the app.
### Terminology
To avoid any confusion here are our definitions of some important terms:
- **App**: A Django application. An app is always part of a distribution package
- **Distribution package** A Python package that can be installed via pip or setuptools. Distribution packages can contain several apps.
- **Requirement**: A requirement is a condition that distribution packages can define to specify dependencies to environments or other distribution packages with specific versions. For example the distribution package django-eveuniverse can have the requirement `"django-esi>=2.0"`, which means is requires the package django-esi in at leasts version 2.0
### Operation modes
You can run Package Monitor in one of two modes:
- Keep everything updated
- Keep apps and selected distribution packages updated
#### Keep everything updated
In this mode Package Monitor will monitor all installed distribution packages. In this mode you will be informed you about updates to any of your distribution packages.
This is the default operation mode.
#### Keep apps and selected distribution packages updated
With this mode Package Monitor will monitor only those distribution packages that contain actually installed Django apps. In this mode you will be informed if there is an update to any of your apps. Note that in mode A other installed distributions packages will not be shown.
To activate this mode set `PACKAGE_MONITOR_SHOW_ALL_PACKAGES` to `False` in your local settings.
You can also add some additional distributions to be monitored. For example you might want to add celery.
See also [Settings](#settings) for an overview of all settings.
### Latest version
Package Monitor will automatically determine a latest version for a distribution package from PyPI. Note that this can differ from the latest version shown on PyPI, because of additional considerations:
First, Package Monitor will take into account all requirements of all installed distribution packages. For example if the Alliance Auth has the requirement "Django<3", then it will only show Django 2.x as latest, since Django 3.x would not fullfil the requirement set by Alliance Auth.
Second, Package Monitor will in general ignore pre-releases and consider stable releases for updates only. The only exception is if the current package also is a pre release. For example you may have Black installed as beta release, therefore the app will also suggest newer beta releases.
## Settings
Here is a list of available settings for this app. They can be configured by adding them to your AA settings file (`local.py`).
Note that all settings are optional and the app will use the documented default settings if they are not used.
Name|Description|Default
--|--|--
Name|Description|Default
--|--|--
`PACKAGE_MONITOR_CUSTOM_REQUIREMENTS`|List of custom requirements that all potential updates are checked against. Example: ["gunicorn<20"]|`[]`
`PACKAGE_MONITOR_EXCLUDE_PACKAGES`|Names of distribution packages to be excluded.|`[]`
`PACKAGE_MONITOR_INCLUDE_PACKAGES`|Names of additional distribution packages to be monitored.|`[]`
`PACKAGE_MONITOR_NOTIFICATIONS_ENABLED`|Whether to notify when an update is available for a currently installed distribution package.|`False`
`PACKAGE_MONITOR_NOTIFICATIONS_MAX_DELAY`|Maximum delay in seconds between the scheduled event for firing a notification and the time the notification is issued. This value should be synchronized with the timing of the recurring task.|`5400`
`PACKAGE_MONITOR_NOTIFICATIONS_REPEAT`|Whether to repeat notifying about the same updates.|`False`
`PACKAGE_MONITOR_NOTIFICATIONS_SCHEDULE`|When to send notifications about updates. If not set, update notifications can be send every time the regular task runs. The schedule can be defined in natural language. Examples: "every day at 10:00", "every saturday at 18:00", "every first saturday every month at 15:00". For more information about the syntax please see: [recurrent package](https://github.com/kvh/recurrent)|``
`PACKAGE_MONITOR_PROTECTED_PACKAGES`|Names of protected packages. Updates can include requirements for updating other packages, which can potentially break the current AA installation. For example: You have Django 4.2 installed and an update to a package requires Django 5 or higher. Then installing that package may break your installation. When enabled Package Monitor will not show updates, which would cause an indirect update of a protected package. And empty list disables this feature.|`['allianceauth', 'django']`
`PACKAGE_MONITOR_SHOW_ALL_PACKAGES`|Whether to show all distribution packages, as opposed to only showing packages that contain Django apps.|`True`
`PACKAGE_MONITOR_SHOW_EDITABLE_PACKAGES`|Whether to show distribution packages installed as editable. Since version information about editable packages is often outdated, this type of packages are not shown by default.|`False`
## Permissions
This is an overview of all permissions used by this app. Note that all permissions are in the "general" section.
Name | Purpose | Code
-- | -- | --
Can access this app and view | User can access the app and also request updates to the list of distribution packages | `general.basic_access`
## Management Commands
This app also provides a CLI tool. This tool gives you access to additional features, which are meant to support admins support with analyzing potential issues.
Please run the following command to see all available features:
```sh
python manage.py packagemonitorcli -h
```
Raw data
{
"_id": null,
"home_page": null,
"name": "aa-package-monitor",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Erik Kalkoken <kalkoken87@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c2/41/255fb73ee68e6a200917132c611492e1db798cd260330151445bd867d150/aa_package_monitor-2.0.0.tar.gz",
"platform": null,
"description": "# Package Monitor\n\nAn app for keeping track of installed packages and outstanding updates with Alliance Auth.\n\n[](https://pypi.org/project/aa-package-monitor/)\n[](https://pypi.org/project/aa-package-monitor/)\n[](https://pypi.org/project/aa-package-monitor/)\n[](https://gitlab.com/ErikKalkoken/aa-package-monitor/-/pipelines)\n[](https://codecov.io/gl/ErikKalkoken/aa-package-monitor)\n[](https://gitlab.com/ErikKalkoken/aa-package-monitor/-/blob/master/LICENSE)\n[](https://github.com/pre-commit/pre-commit)\n[](https://github.com/psf/black)\n[](https://discord.gg/zmh52wnfvM)\n\n## Contents\n\n- [Overview](#overview)\n- [Screenshots](#screenshots)\n- [Installation](#installation)\n- [Updating](#updating)\n- [User Guide](#user-guide)\n- [Settings](#settings)\n- [Permissions](#permissions)\n- [Management Commands](#management-commands)\n- [Change Log](CHANGELOG.md)\n\n## Overview\n\nPackage Monitor is an app for Alliance Auth that helps you keep your installation up-to-date. It shows you all installed distributions packages and will automatically notify you, when there are updates available.\n\nFeatures:\n\n- Shows list of installed distributions packages with related Django apps (if any)\n- Identifies new valid releases for installed packages on PyPI\n- Notifies user which installed packages are outdated and should be updated\n- Shows the number of outdated packages as badge in the sidebar\n- Takes into account the requirements of all installed packages and the current Python version when recommending updates\n- Option to add distribution pages to the monitor which are not related to Django apps\n- Option to show all known distribution packages (as opposed to only the ones that belong to installed Django apps)\n- Copy the respective command for a package update to your clipboard directly from the package list\n- Can automatically notify admins when there is an update available for a currently installed package\n- Supported languages: English :us:, German :de: and Russian :ru:\n\n>**Hint**: Update notifications are sent as AA notifications to all admins. We recommend using [Discord Notify](https://gitlab.com/ErikKalkoken/aa-discordnotify) to automatically forward those notifications to Discord as DMs.\n\n## Screenshots\n\n\n\n## Installation\n\n### Step 1 - Check Preconditions\n\nPlease make sure you meet all preconditions before proceeding:\n\n- Package Monitor is a plugin for [Alliance Auth](https://gitlab.com/allianceauth/allianceauth). If you don't have Alliance Auth running already, please install it first before proceeding. (see the official [AA installation guide](https://allianceauth.readthedocs.io/en/latest/installation/auth/allianceauth/) for details)\n\n### Step 2 - Install app\n\nMake sure you are in the virtual environment (venv) of your Alliance Auth installation. Then install the newest release from PYPI:\n\n```bash\npip install aa-package-monitor\n```\n\n### Step 3 - Configure settings\n\nAdd `'package_monitor'` to `INSTALLED_APPS`.\n\nAdd the following lines to your `local.py` to enable regular checking for updates:\n\n```Python\nCELERYBEAT_SCHEDULE['package_monitor_update_distributions'] = {\n 'task': 'package_monitor.tasks.update_distributions',\n 'schedule': crontab(minute='*/60'),\n}\n```\n\nFinally, please also take a moment to consider how often you want to receive update notifications. The default is immediate, but you can also chose to receive notifications after a timeout, e.g. only once per 24 hours or once per week. If you choose a timeout you can also choose to get repeated notifications about the same updates, like a reminder. For more details please see the [Settings](#settings).\n\n### Step 4 - Finalize installation\n\nRun migrations & copy static files\n\n```bash\npython manage.py migrate\npython manage.py collectstatic\n```\n\nRestart your supervisor services for Auth\n\n### Step 5 - Initial data load\n\nLast, but not least perform an initial data load of all distribution packages by running the following command:\n\n```bash\npython manage.py package_monitor_refresh\n```\n\n## Updating\n\n```bash\npip install -U aa-package-monitor\n\npython manage.py collectstatic\n\npython manage.py migrate\n```\n\nFinally restart your AA supervisor services.\n\n## User Guide\n\nThis section explains how to use the app.\n\n### Terminology\n\nTo avoid any confusion here are our definitions of some important terms:\n\n- **App**: A Django application. An app is always part of a distribution package\n- **Distribution package** A Python package that can be installed via pip or setuptools. Distribution packages can contain several apps.\n- **Requirement**: A requirement is a condition that distribution packages can define to specify dependencies to environments or other distribution packages with specific versions. For example the distribution package django-eveuniverse can have the requirement `\"django-esi>=2.0\"`, which means is requires the package django-esi in at leasts version 2.0\n\n### Operation modes\n\nYou can run Package Monitor in one of two modes:\n\n- Keep everything updated\n- Keep apps and selected distribution packages updated\n\n#### Keep everything updated\n\nIn this mode Package Monitor will monitor all installed distribution packages. In this mode you will be informed you about updates to any of your distribution packages.\n\nThis is the default operation mode.\n\n#### Keep apps and selected distribution packages updated\n\nWith this mode Package Monitor will monitor only those distribution packages that contain actually installed Django apps. In this mode you will be informed if there is an update to any of your apps. Note that in mode A other installed distributions packages will not be shown.\n\nTo activate this mode set `PACKAGE_MONITOR_SHOW_ALL_PACKAGES` to `False` in your local settings.\n\nYou can also add some additional distributions to be monitored. For example you might want to add celery.\n\nSee also [Settings](#settings) for an overview of all settings.\n\n### Latest version\n\nPackage Monitor will automatically determine a latest version for a distribution package from PyPI. Note that this can differ from the latest version shown on PyPI, because of additional considerations:\n\nFirst, Package Monitor will take into account all requirements of all installed distribution packages. For example if the Alliance Auth has the requirement \"Django<3\", then it will only show Django 2.x as latest, since Django 3.x would not fullfil the requirement set by Alliance Auth.\n\nSecond, Package Monitor will in general ignore pre-releases and consider stable releases for updates only. The only exception is if the current package also is a pre release. For example you may have Black installed as beta release, therefore the app will also suggest newer beta releases.\n\n## Settings\n\nHere is a list of available settings for this app. They can be configured by adding them to your AA settings file (`local.py`).\n\nNote that all settings are optional and the app will use the documented default settings if they are not used.\n\nName|Description|Default\n--|--|--\nName|Description|Default\n--|--|--\n`PACKAGE_MONITOR_CUSTOM_REQUIREMENTS`|List of custom requirements that all potential updates are checked against. Example: [\"gunicorn<20\"]|`[]`\n`PACKAGE_MONITOR_EXCLUDE_PACKAGES`|Names of distribution packages to be excluded.|`[]`\n`PACKAGE_MONITOR_INCLUDE_PACKAGES`|Names of additional distribution packages to be monitored.|`[]`\n`PACKAGE_MONITOR_NOTIFICATIONS_ENABLED`|Whether to notify when an update is available for a currently installed distribution package.|`False`\n`PACKAGE_MONITOR_NOTIFICATIONS_MAX_DELAY`|Maximum delay in seconds between the scheduled event for firing a notification and the time the notification is issued. This value should be synchronized with the timing of the recurring task.|`5400`\n`PACKAGE_MONITOR_NOTIFICATIONS_REPEAT`|Whether to repeat notifying about the same updates.|`False`\n`PACKAGE_MONITOR_NOTIFICATIONS_SCHEDULE`|When to send notifications about updates. If not set, update notifications can be send every time the regular task runs. The schedule can be defined in natural language. Examples: \"every day at 10:00\", \"every saturday at 18:00\", \"every first saturday every month at 15:00\". For more information about the syntax please see: [recurrent package](https://github.com/kvh/recurrent)|``\n`PACKAGE_MONITOR_PROTECTED_PACKAGES`|Names of protected packages. Updates can include requirements for updating other packages, which can potentially break the current AA installation. For example: You have Django 4.2 installed and an update to a package requires Django 5 or higher. Then installing that package may break your installation. When enabled Package Monitor will not show updates, which would cause an indirect update of a protected package. And empty list disables this feature.|`['allianceauth', 'django']`\n`PACKAGE_MONITOR_SHOW_ALL_PACKAGES`|Whether to show all distribution packages, as opposed to only showing packages that contain Django apps.|`True`\n`PACKAGE_MONITOR_SHOW_EDITABLE_PACKAGES`|Whether to show distribution packages installed as editable. Since version information about editable packages is often outdated, this type of packages are not shown by default.|`False`\n\n## Permissions\n\nThis is an overview of all permissions used by this app. Note that all permissions are in the \"general\" section.\n\nName | Purpose | Code\n-- | -- | --\nCan access this app and view | User can access the app and also request updates to the list of distribution packages | `general.basic_access`\n\n## Management Commands\n\nThis app also provides a CLI tool. This tool gives you access to additional features, which are meant to support admins support with analyzing potential issues.\n\nPlease run the following command to see all available features:\n\n```sh\npython manage.py packagemonitorcli -h\n```\n\n",
"bugtrack_url": null,
"license": null,
"summary": "An app that helps keep track of installed packages",
"version": "2.0.0",
"project_urls": {
"Changelog": "https://gitlab.com/ErikKalkoken/aa-package-monitor/-/blob/master/CHANGELOG.md",
"Homepage": "https://gitlab.com/ErikKalkoken/aa-package-monitor",
"Source": "https://gitlab.com/ErikKalkoken/aa-package-monitor",
"Tracker": "https://gitlab.com/ErikKalkoken/aa-package-monitor/-/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6347249c2c17c87cb7b6f033ad3295c492a5236b0c499523b7877515ba6269af",
"md5": "bac9ca5161cceef93382708b2f154574",
"sha256": "1cfaf33e6e946284fdf800e765fd00c6259076f6c6afe117a4a3ae278ffca27b"
},
"downloads": -1,
"filename": "aa_package_monitor-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bac9ca5161cceef93382708b2f154574",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 114174,
"upload_time": "2024-09-06T14:27:11",
"upload_time_iso_8601": "2024-09-06T14:27:11.950386Z",
"url": "https://files.pythonhosted.org/packages/63/47/249c2c17c87cb7b6f033ad3295c492a5236b0c499523b7877515ba6269af/aa_package_monitor-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c241255fb73ee68e6a200917132c611492e1db798cd260330151445bd867d150",
"md5": "06b089af36fac1d71111a6945c017673",
"sha256": "f16a2621422b153062f3044c1f88ae0f479fe1f9b01de75e8725d59baf7a0e07"
},
"downloads": -1,
"filename": "aa_package_monitor-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "06b089af36fac1d71111a6945c017673",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 88684,
"upload_time": "2024-09-06T14:27:14",
"upload_time_iso_8601": "2024-09-06T14:27:14.022572Z",
"url": "https://files.pythonhosted.org/packages/c2/41/255fb73ee68e6a200917132c611492e1db798cd260330151445bd867d150/aa_package_monitor-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-06 14:27:14",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "ErikKalkoken",
"gitlab_project": "aa-package-monitor",
"lcname": "aa-package-monitor"
}
