# CengalAppDirPathFinder
CengalAppDirPathFinder is a cross-platform Python module designed to simplify the process of locating OS-recommended directories for application data, cache, logs, and more. It seamlessly integrates with Windows, Linux, and macOS, utilizing platform-specific standards like `KNOWNFOLDERID constants` on Windows, `XDG standards` on Linux, and `NSSearchPathForDirectoriesInDomains` on macOS. This module offers a unified API for accessing various types of directories, such as local, roaming, and program-specific paths, enhancing application compatibility and data management across different operating systems.
# Installation
```bash
pip install cengal_app_dir_path_finder
```
# Documentation
## Import
```python
from cengal_app_dir_path_finder import AppDirectoryType, AppDirPath
```
## Usage
```python
import os
from cengal_app_dir_path_finder import AppDirectoryType, AppDirPath
app_dir_path: AppDirPath = AppDirPath()
local_data_dir_path: str = app_dir_path(AppDirectoryType.local_data, 'MyApplicationName')
settings_json_path: str = os.path.join(local_data_dir_path, 'settings.json')
with open(settings_json_path, 'w') as file:
file.write(my_app_settings)
```
## Supported foler types
`AppDirectoryType` is an enum of all supported kinds of directories.
`AppDirectoryType` Fields:
* `local_data`: Local user-specific data storage, not shared across users, ideal for storing user preferences, game scores, etc.
* `local_low_data`: Low privilege local data storage for sandboxed or security-sensitive applications.
* `roaming_data`: User-specific data that may sync across devices, suitable for configurations and settings.
* `local_cache`: Stores temporary, user-specific cache data that can be regenerated as needed.
* `local_low_cache`: Similar to local_cache but for applications requiring lower access privileges.
* `roaming_cache`: User-specific cache data that could be shared and synced across devices.
* `local_temp`: Temporary files and data specific to the current user.
* `local_low_temp`: Temporary files for applications with lower privileges.
* `roaming_temp`: Temporary user-specific files that might be synced across devices.
* `local_log`: Logs and operation records for the current user.
* `local_low_log`: Logs for low privilege applications.
* `roaming_log`: User-specific logs that might be shared across devices.
* `local_config`: Configuration files and settings for the current user.
* `local_low_config`: Configuration for applications with lower privileges.
* `roaming_config`: Configurations that might be synced across a user's devices.
* `local_runtime`: User-specific runtime data like sockets and named pipes.
* `local_low_runtime`: Runtime data for applications with lower privileges.
* `roaming_runtime`: User-specific runtime data that could be synced across devices.
* `program_files`: Static data shared among all users, like application binaries.
* `program_files_common`: Shared libraries and common resources for multiple applications.
* `program_data`: Non-static data shared among users, like shared databases.
* `program_cache`: Cache for shared applications and services.
* `program_temp`: Temporary files for shared applications.
* `program_log`: Log files for system-wide applications.
* `program_config`: Configuration files for system-wide applications.
* `program_runtime`: System-wide runtime data like global sockets and named pipes.
* `user_profile_data`: User-specific application data within the user's home directory.
* `user_profile_program_files`: Static data specific to user-installed applications.
* `user_profile_program_files_common`: Shared resources for user-specific applications.
* `local_static_data`: Static data specific to the local user, not frequently modified.
* `local_low_static_data`: Static data for lower privilege user applications.
* `roaming_static_data`: User-specific static data that may sync across devices.
* `program_static_data`: Static data shared among all users and applications.
## AppDirPath methods
### `__call__(...)`
`def __call__(self, dir_type: AppDirectoryType, app_name_or_path: DirNameOrPath, with_structure: bool = True, ensure_dir: bool = True) -> str:`
Constructs path of the requestet directory type taking into account provided application name.
* `with_structure`:
* `False`: determines base directory provided by OS and followed with an application name
* `True`: determines base directory provided by OS, followed with an application name and completed with a suffixes like 'cache', 'config', 'log', etc.
* `ensure_dir`:
* `True`: creates directory sequence if does not exists
### `cached(...)`
`def cached(self, dir_type: AppDirectoryType, app_name_or_path: DirNameOrPath, with_structure: bool = True, ensure_dir: bool = True) -> str:`
Cached version. Much faster in a repetitive requests.
## Global app instances of AppDirPath
An `Instance` service from the `Cengal.Coroutines` holds globally accessible instance of the AppDirPath as well as globally acessible field for an application name:
```python
{
...
'app_name': str(),
'app_name_for_fs': str(),
'app_version': tuple(),
'app_version_str': str(),
AppDirPath: AppDirPath(),
'app_data_dir_path_type': AppDirectoryType.local_data,
'app_cache_dir_path_type': AppDirectoryType.local_cache,
'app_temp_dir_path_type': AppDirectoryType.local_temp,
'app_log_dir_path_type': AppDirectoryType.local_log,
'app_config_dir_path_type': AppDirectoryType.local_config,
'app_runtime_dir_path_type': AppDirectoryType.local_runtime,
...
}
```
Several `Cengal.Coroutines.Services` using these fields and instances in their work. For example such services as `db` (async LMDB) and `log`.
Short example of proper usage:
```python
from cengal_app_dir_path_finder import AppDirectoryType, AppDirPath
from cengal.parallel_execution.coroutines.coro_scheduler import cs_acoro
from cengal.parallel_execution.coroutines.coro_standard_services.instance import afast_wait, fast_get, fast_set
from uuid import uuid4
MY_APP_CONFIGURATION_COMPLETED_FLAG_NAME: str = f'My Application Mandatory Configuration Complited {uuid4()}'
@cs_acoro
async def set_app_name(app_name: str) -> None:
fast_set('app_name_for_fs', app_name)
fast_set(MY_APP_CONFIGURATION_COMPLETED_FLAG_NAME, None)
@cs_acoro
async def get_local_temp_dir() -> str:
await afast_wait(MY_APP_CONFIGURATION_COMPLETED_FLAG_NAME)
app_dir_path: AppDirPath = fast_get(AppDirPath)
return app_dir_path.cached(fast_get('app_temp_dir_path_type'), fast_get('app_name_for_fs'))
```
Same example but a bit faster in an execution performance terms:
```python
from cengal.file_system.app_fs_structure.app_dir_path import AppDirectoryType, AppDirPath # totaly the same import as in a previous example
from cengal.parallel_execution.coroutines.coro_scheduler import Interface
from cengal.parallel_execution.coroutines.coro_standard_services.instance import afast_wait_explicit, fast_get_explicit, fast_set_explicit
from uuid import uuid4
MY_APP_CONFIGURATION_COMPLETED_FLAG_NAME: str = f'My Application Mandatory Configuration Complited {uuid4()}'
async def set_app_name(i: Interface, app_name: str) -> None:
fast_set_explicit(i, 'app_name_for_fs', app_name)
fast_set_explicit(i, MY_APP_CONFIGURATION_COMPLETED_FLAG_NAME, None)
async def get_local_temp_dir(i: Interface) -> str:
await afast_wait_explicit(i, MY_APP_CONFIGURATION_COMPLETED_FLAG_NAME)
app_dir_path: AppDirPath = fast_get_explicit(i, AppDirPath)
return app_dir_path.cached(fast_get_explicit(i, 'app_temp_dir_path_type'),
fast_get_explicit(i, 'app_name_for_fs'))
```
# Based on Cengal
Represents part of Cengal library:
* https://pypi.org/project/cengal/
* https://github.com/FI-Mihej/Cengal
An equivalent import:
```python
from cengal.file_system.app_fs_structure.app_dir_path import AppDirectoryType, AppDirPath
```
Cengal library can be installed by:
```bash
pip install cengal
```
# Projects using Cengal
* [flet_async](https://github.com/FI-Mihej/flet_async) - wrapper which makes [Flet](https://github.com/flet-dev/flet) async and brings booth Cengal.coroutines and asyncio to Flet (Flutter based UI)
* [justpy_containers](https://github.com/FI-Mihej/justpy_containers) - wrapper around [JustPy](https://github.com/justpy-org/justpy) in order to bring more security and more production-needed features to JustPy (VueJS based UI)
* [Bensbach](https://github.com/FI-Mihej/Bensbach) - decompiler from Unreal Engine 3 bytecode to a Lisp-like script and compiler back to Unreal Engine 3 bytecode. Made for a game modding purposes
* [Realistic-Damage-Model-mod-for-Long-War](https://github.com/FI-Mihej/Realistic-Damage-Model-mod-for-Long-War) - Mod for both the original XCOM:EW and the mod Long War. Was made with a Bensbach, which was made with Cengal
* [SmartCATaloguer.com](http://www.smartcataloguer.com/index.html) - TagDB based catalog of images (tags), music albums (genre tags) and apps (categories)
# License
Copyright © 2012-2023 ButenkoMS. All rights reserved.
Licensed under the Apache License, Version 2.0.
Raw data
{
"_id": null,
"home_page": "",
"name": "cengal-app-dir-path-finder",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "Linux,Windows,app directory,application data,cache management,cengal,config storage,crossplatform,data management,directory access,environment paths,file paths,log storage,macOS,os integration,path finder,system directories,user data",
"author": "",
"author_email": "ButenkoMS <gtalk@butenkoms.space>",
"download_url": "https://files.pythonhosted.org/packages/8b/10/55c1b8ae633efec3bd892e1a973c2fb7b93c0e2b67ac91bfa2847de41763/cengal_app_dir_path_finder-1.0.0.tar.gz",
"platform": null,
"description": "# CengalAppDirPathFinder\n\nCengalAppDirPathFinder is a cross-platform Python module designed to simplify the process of locating OS-recommended directories for application data, cache, logs, and more. It seamlessly integrates with Windows, Linux, and macOS, utilizing platform-specific standards like `KNOWNFOLDERID constants` on Windows, `XDG standards` on Linux, and `NSSearchPathForDirectoriesInDomains` on macOS. This module offers a unified API for accessing various types of directories, such as local, roaming, and program-specific paths, enhancing application compatibility and data management across different operating systems.\n\n# Installation\n\n```bash\npip install cengal_app_dir_path_finder\n```\n\n# Documentation\n\n## Import\n\n```python\nfrom cengal_app_dir_path_finder import AppDirectoryType, AppDirPath\n```\n\n## Usage\n\n```python\nimport os\nfrom cengal_app_dir_path_finder import AppDirectoryType, AppDirPath\n\napp_dir_path: AppDirPath = AppDirPath()\nlocal_data_dir_path: str = app_dir_path(AppDirectoryType.local_data, 'MyApplicationName')\nsettings_json_path: str = os.path.join(local_data_dir_path, 'settings.json')\nwith open(settings_json_path, 'w') as file:\n file.write(my_app_settings)\n```\n\n## Supported foler types\n\n`AppDirectoryType` is an enum of all supported kinds of directories.\n\n`AppDirectoryType` Fields:\n* `local_data`: Local user-specific data storage, not shared across users, ideal for storing user preferences, game scores, etc.\n* `local_low_data`: Low privilege local data storage for sandboxed or security-sensitive applications.\n* `roaming_data`: User-specific data that may sync across devices, suitable for configurations and settings.\n* `local_cache`: Stores temporary, user-specific cache data that can be regenerated as needed.\n* `local_low_cache`: Similar to local_cache but for applications requiring lower access privileges.\n* `roaming_cache`: User-specific cache data that could be shared and synced across devices.\n* `local_temp`: Temporary files and data specific to the current user.\n* `local_low_temp`: Temporary files for applications with lower privileges.\n* `roaming_temp`: Temporary user-specific files that might be synced across devices.\n* `local_log`: Logs and operation records for the current user.\n* `local_low_log`: Logs for low privilege applications.\n* `roaming_log`: User-specific logs that might be shared across devices.\n* `local_config`: Configuration files and settings for the current user.\n* `local_low_config`: Configuration for applications with lower privileges.\n* `roaming_config`: Configurations that might be synced across a user's devices.\n* `local_runtime`: User-specific runtime data like sockets and named pipes.\n* `local_low_runtime`: Runtime data for applications with lower privileges.\n* `roaming_runtime`: User-specific runtime data that could be synced across devices.\n* `program_files`: Static data shared among all users, like application binaries.\n* `program_files_common`: Shared libraries and common resources for multiple applications.\n* `program_data`: Non-static data shared among users, like shared databases.\n* `program_cache`: Cache for shared applications and services.\n* `program_temp`: Temporary files for shared applications.\n* `program_log`: Log files for system-wide applications.\n* `program_config`: Configuration files for system-wide applications.\n* `program_runtime`: System-wide runtime data like global sockets and named pipes.\n* `user_profile_data`: User-specific application data within the user's home directory.\n* `user_profile_program_files`: Static data specific to user-installed applications.\n* `user_profile_program_files_common`: Shared resources for user-specific applications.\n* `local_static_data`: Static data specific to the local user, not frequently modified.\n* `local_low_static_data`: Static data for lower privilege user applications.\n* `roaming_static_data`: User-specific static data that may sync across devices.\n* `program_static_data`: Static data shared among all users and applications.\n\n## AppDirPath methods\n\n### `__call__(...)`\n\n`def __call__(self, dir_type: AppDirectoryType, app_name_or_path: DirNameOrPath, with_structure: bool = True, ensure_dir: bool = True) -> str:`\n\nConstructs path of the requestet directory type taking into account provided application name.\n* `with_structure`:\n * `False`: determines base directory provided by OS and followed with an application name\n * `True`: determines base directory provided by OS, followed with an application name and completed with a suffixes like 'cache', 'config', 'log', etc.\n* `ensure_dir`:\n * `True`: creates directory sequence if does not exists\n\n### `cached(...)`\n\n`def cached(self, dir_type: AppDirectoryType, app_name_or_path: DirNameOrPath, with_structure: bool = True, ensure_dir: bool = True) -> str:`\n\nCached version. Much faster in a repetitive requests.\n\n## Global app instances of AppDirPath\n\nAn `Instance` service from the `Cengal.Coroutines` holds globally accessible instance of the AppDirPath as well as globally acessible field for an application name:\n\n```python\n{\n ...\n 'app_name': str(),\n 'app_name_for_fs': str(),\n 'app_version': tuple(),\n 'app_version_str': str(),\n AppDirPath: AppDirPath(),\n 'app_data_dir_path_type': AppDirectoryType.local_data,\n 'app_cache_dir_path_type': AppDirectoryType.local_cache,\n 'app_temp_dir_path_type': AppDirectoryType.local_temp,\n 'app_log_dir_path_type': AppDirectoryType.local_log,\n 'app_config_dir_path_type': AppDirectoryType.local_config,\n 'app_runtime_dir_path_type': AppDirectoryType.local_runtime,\n ...\n}\n```\n\nSeveral `Cengal.Coroutines.Services` using these fields and instances in their work. For example such services as `db` (async LMDB) and `log`.\n\nShort example of proper usage:\n\n```python\nfrom cengal_app_dir_path_finder import AppDirectoryType, AppDirPath\nfrom cengal.parallel_execution.coroutines.coro_scheduler import cs_acoro\nfrom cengal.parallel_execution.coroutines.coro_standard_services.instance import afast_wait, fast_get, fast_set\nfrom uuid import uuid4\n\n\nMY_APP_CONFIGURATION_COMPLETED_FLAG_NAME: str = f'My Application Mandatory Configuration Complited {uuid4()}'\n\n\n@cs_acoro\nasync def set_app_name(app_name: str) -> None:\n fast_set('app_name_for_fs', app_name)\n fast_set(MY_APP_CONFIGURATION_COMPLETED_FLAG_NAME, None)\n\n\n@cs_acoro\nasync def get_local_temp_dir() -> str:\n await afast_wait(MY_APP_CONFIGURATION_COMPLETED_FLAG_NAME)\n app_dir_path: AppDirPath = fast_get(AppDirPath)\n return app_dir_path.cached(fast_get('app_temp_dir_path_type'), fast_get('app_name_for_fs'))\n```\n\nSame example but a bit faster in an execution performance terms:\n\n```python\nfrom cengal.file_system.app_fs_structure.app_dir_path import AppDirectoryType, AppDirPath # totaly the same import as in a previous example\nfrom cengal.parallel_execution.coroutines.coro_scheduler import Interface\nfrom cengal.parallel_execution.coroutines.coro_standard_services.instance import afast_wait_explicit, fast_get_explicit, fast_set_explicit\nfrom uuid import uuid4\n\n\nMY_APP_CONFIGURATION_COMPLETED_FLAG_NAME: str = f'My Application Mandatory Configuration Complited {uuid4()}'\n\n\nasync def set_app_name(i: Interface, app_name: str) -> None:\n fast_set_explicit(i, 'app_name_for_fs', app_name)\n fast_set_explicit(i, MY_APP_CONFIGURATION_COMPLETED_FLAG_NAME, None)\n\n\nasync def get_local_temp_dir(i: Interface) -> str:\n await afast_wait_explicit(i, MY_APP_CONFIGURATION_COMPLETED_FLAG_NAME)\n app_dir_path: AppDirPath = fast_get_explicit(i, AppDirPath)\n return app_dir_path.cached(fast_get_explicit(i, 'app_temp_dir_path_type'), \n fast_get_explicit(i, 'app_name_for_fs'))\n```\n\n# Based on Cengal\n\nRepresents part of Cengal library:\n* https://pypi.org/project/cengal/\n* https://github.com/FI-Mihej/Cengal\n\nAn equivalent import:\n```python\nfrom cengal.file_system.app_fs_structure.app_dir_path import AppDirectoryType, AppDirPath\n```\n\nCengal library can be installed by:\n\n```bash\npip install cengal\n```\n\n\n# Projects using Cengal\n\n* [flet_async](https://github.com/FI-Mihej/flet_async) - wrapper which makes [Flet](https://github.com/flet-dev/flet) async and brings booth Cengal.coroutines and asyncio to Flet (Flutter based UI)\n* [justpy_containers](https://github.com/FI-Mihej/justpy_containers) - wrapper around [JustPy](https://github.com/justpy-org/justpy) in order to bring more security and more production-needed features to JustPy (VueJS based UI)\n* [Bensbach](https://github.com/FI-Mihej/Bensbach) - decompiler from Unreal Engine 3 bytecode to a Lisp-like script and compiler back to Unreal Engine 3 bytecode. Made for a game modding purposes\n* [Realistic-Damage-Model-mod-for-Long-War](https://github.com/FI-Mihej/Realistic-Damage-Model-mod-for-Long-War) - Mod for both the original XCOM:EW and the mod Long War. Was made with a Bensbach, which was made with Cengal\n* [SmartCATaloguer.com](http://www.smartcataloguer.com/index.html) - TagDB based catalog of images (tags), music albums (genre tags) and apps (categories)\n\n# License\n\nCopyright \u00a9 2012-2023 ButenkoMS. All rights reserved.\n\nLicensed under the Apache License, Version 2.0.\n",
"bugtrack_url": null,
"license": "",
"summary": "Offering a unified API for easy retrieval of OS-specific application directories, enhancing data management across Windows, Linux, and macOS",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/FI-Mihej/cengal_app_dir_path_finder"
},
"split_keywords": [
"linux",
"windows",
"app directory",
"application data",
"cache management",
"cengal",
"config storage",
"crossplatform",
"data management",
"directory access",
"environment paths",
"file paths",
"log storage",
"macos",
"os integration",
"path finder",
"system directories",
"user data"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8293c7ddf987c16ff78482be718c18c7e7845f4fc66104ed58989099d24a6a59",
"md5": "3a50e08d0488a9969a63485aacb18b5f",
"sha256": "85bbb7d27fcc73ce30e59edf96d36515335eaec4e097829ee6b8296c10946e34"
},
"downloads": -1,
"filename": "cengal_app_dir_path_finder-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3a50e08d0488a9969a63485aacb18b5f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 10211,
"upload_time": "2023-11-24T00:22:50",
"upload_time_iso_8601": "2023-11-24T00:22:50.767781Z",
"url": "https://files.pythonhosted.org/packages/82/93/c7ddf987c16ff78482be718c18c7e7845f4fc66104ed58989099d24a6a59/cengal_app_dir_path_finder-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8b1055c1b8ae633efec3bd892e1a973c2fb7b93c0e2b67ac91bfa2847de41763",
"md5": "2f083b672e1ba456f95c8a03d3751618",
"sha256": "a21112e85b93860d6de263fdc1fb29bb337dd81f901f89bece464354ed45c301"
},
"downloads": -1,
"filename": "cengal_app_dir_path_finder-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "2f083b672e1ba456f95c8a03d3751618",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 10799,
"upload_time": "2023-11-24T00:22:53",
"upload_time_iso_8601": "2023-11-24T00:22:53.423761Z",
"url": "https://files.pythonhosted.org/packages/8b/10/55c1b8ae633efec3bd892e1a973c2fb7b93c0e2b67ac91bfa2847de41763/cengal_app_dir_path_finder-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-24 00:22:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "FI-Mihej",
"github_project": "cengal_app_dir_path_finder",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "hatch",
"specs": []
},
{
"name": "twine",
"specs": []
},
{
"name": "cengal_light",
"specs": []
},
{
"name": "pyobjc",
"specs": []
}
],
"lcname": "cengal-app-dir-path-finder"
}
JSON
