Offering a unified API for easy retrieval of OS-specific application directories, enhancing data management across Windows, Linux, and macOS
Project description
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
pip install cengal_app_dir_path_finder
Documentation
Import
from cengal_app_dir_path_finder import AppDirectoryType, AppDirPath
Usage
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 nameTrue
: 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:
{
...
'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:
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:
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:
An equivalent import:
from cengal.file_system.app_fs_structure.app_dir_path import AppDirectoryType, AppDirPath
Cengal library can be installed by:
pip install cengal
Projects using Cengal
- flet_async - wrapper which makes Flet async and brings booth Cengal.coroutines and asyncio to Flet (Flutter based UI)
- justpy_containers - wrapper around JustPy in order to bring more security and more production-needed features to JustPy (VueJS based UI)
- 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 - Mod for both the original XCOM:EW and the mod Long War. Was made with a Bensbach, which was made with Cengal
- SmartCATaloguer.com - 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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for cengal_app_dir_path_finder-1.0.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | a21112e85b93860d6de263fdc1fb29bb337dd81f901f89bece464354ed45c301 |
|
MD5 | 2f083b672e1ba456f95c8a03d3751618 |
|
BLAKE2b-256 | 8b1055c1b8ae633efec3bd892e1a973c2fb7b93c0e2b67ac91bfa2847de41763 |
Hashes for cengal_app_dir_path_finder-1.0.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 85bbb7d27fcc73ce30e59edf96d36515335eaec4e097829ee6b8296c10946e34 |
|
MD5 | 3a50e08d0488a9969a63485aacb18b5f |
|
BLAKE2b-256 | 8293c7ddf987c16ff78482be718c18c7e7845f4fc66104ed58989099d24a6a59 |