From 2fb6f7e15a4a192f24e39a386d42bb4e1c804402 Mon Sep 17 00:00:00 2001 From: Frank Martinez Date: Wed, 24 Sep 2025 12:12:06 -0500 Subject: [PATCH] [bindings] ApplicationDirectories --- src/App/ApplicationDirectories.pyi | 90 ++++++++++++++++++------------ 1 file changed, 54 insertions(+), 36 deletions(-) diff --git a/src/App/ApplicationDirectories.pyi b/src/App/ApplicationDirectories.pyi index ee3419eda8..11776c7009 100644 --- a/src/App/ApplicationDirectories.pyi +++ b/src/App/ApplicationDirectories.pyi @@ -1,38 +1,33 @@ -from Base.PyObjectBase import PyObjectBase -from typing import List +# SPDX-License: LGPL-2.1-or-later +from __future__ import annotations + +from Base.PyObjectBase import PyObjectBase class ApplicationDirectories(PyObjectBase): """ - App.ApplicationDirectories class. + Provides access to the directory versioning methods of its C++ counterpart. - For the time being this class only provides access to the directory versioning methods of its - C++ counterpart. These are all static methods, so no instance is needed. The main methods of + These are all static methods, so no instance is needed. The main methods of this class are migrateAllPaths(), usingCurrentVersionConfig(), and versionStringForPath(). - - Author: Chris Hennes (chennes@pioneerlibrarysystem.org) - Licence: LGPL-2.1-or-later - DeveloperDocu: ApplicationDirectories """ @staticmethod - def usingCurrentVersionConfig(path:str) -> bool: + def usingCurrentVersionConfig(path: str) -> bool: """ - usingCurrentVersionConfig(path) + Determine if a given config path is for the current version of the program. - Determine if a given config path is for the current version of the program - - path : the path to check + Args: + path: The path to check. """ ... @staticmethod - def migrateAllPaths(paths: List[str]) -> None: + def migrateAllPaths(paths: list[str]) -> None: """ - migrateAllPaths(paths) + Migrate a set of versionable configuration directories from the given paths to a new version. - Migrate a set of versionable configuration directories from the given paths to a new - version. The new version's directories cannot exist yet, and the old ones *must* exist. + The new version's directories cannot exist yet, and the old ones *must* exist. If the old paths are themselves versioned, then the new paths will be placed at the same level in the directory structure (e.g., they will be siblings of each entry in paths). If paths are NOT versioned, the new (versioned) copies will be placed *inside* the @@ -41,6 +36,9 @@ class ApplicationDirectories(PyObjectBase): If the list contains the same path multiple times, the duplicates are ignored, so it is safe to pass the same path multiple times. + Args: + paths: List of paths to migrate from. + Examples: Running FreeCAD 1.1, /usr/share/FreeCAD/Config/ -> /usr/share/FreeCAD/Config/v1-1/ Running FreeCAD 1.1, /usr/share/FreeCAD/Config/v1-1 -> raises exception, path exists @@ -49,60 +47,80 @@ class ApplicationDirectories(PyObjectBase): ... @staticmethod - def versionStringForPath(major:int, minor:int) -> str: + def versionStringForPath(major: int, minor: int) -> str: """ - versionStringForPath(major, minor) -> str + Given a major and minor version number. - Given a major and minor version number, return a string that can be used as the name for a - versioned subdirectory. Only returns the version string, not the full path. + Args: + major: Major version number. + minor: Minor version number. + + Returns: + a string that can be used as the name for a versioned subdirectory. + Only returns the version string, not the full path. """ ... @staticmethod - def isVersionedPath(startingPath:str) -> bool: + def isVersionedPath(startingPath: str) -> bool: """ - isVersionedPath(startingPath) -> bool + Determine if a given path is versioned. - Determine if a given path is versioned (that is, if its last component contains - something that this class would have created as a versioned subdirectory). Returns true - for any path that the *current* version of FreeCAD would recognized as versioned, and false - for either something that is not versioned, or something that is versioned but for a later - version of FreeCAD. + That is, if its last component contains something that this class would have + created as a versioned subdirectory). + + Args: + startingPath: The path to check. + + Returns: + True for any path that the *current* version of FreeCAD would recognized as versioned, + and False for either something that is not versioned, or something that is versioned + but for a later version of FreeCAD. """ ... @staticmethod - def mostRecentAvailableConfigVersion(startingPath:str) -> str: + def mostRecentAvailableConfigVersion(startingPath: str) -> str: """ - mostRecentAvailableConfigVersion(startingPath) -> str - Given a base path that is expected to contain versioned subdirectories, locate the directory name (*not* the path, only the final component, the version string itself) corresponding to the most recent version of the software, up to and including the current running version, but NOT exceeding it -- any *later* version whose directories exist in the path is ignored. See also mostRecentConfigFromBase(). + + Args: + startingPath: The path to check. + + Returns: + Most recent available dir name (not path). """ ... @staticmethod def mostRecentConfigFromBase(startingPath: str) -> str: """ - mostRecentConfigFromBase(startingPath) -> str - Given a base path that is expected to contained versioned subdirectories, locate the directory corresponding to the most recent version of the software, up to and including the current version, but NOT exceeding it. Returns the complete path, not just the final component. See also mostRecentAvailableConfigVersion(). + + Args: + startingPath: The base path to check. + + Returns: + Most recent available full path (not just dir name). """ ... @staticmethod def migrateConfig(oldPath: str, newPath: str) -> None: """ - migrateConfig(oldPath, newPath) -> None - A utility method to copy all files and directories from oldPath to newPath, handling the case where newPath might itself be a subdirectory of oldPath (and *not* attempting that otherwise-recursive copy). + + Args: + oldPath: Path from. + newPath: Path to. """ ...