How to make "private" identifiers easily accessible within a package.

[hunterhogan]

N.B. I fixed a mistake and clarified a pronoun.

Representative code

# __init__.py

from stubFileNotFound._theSSOT import settingsPackage

Goals

1. I want stubFileNotFound.stubFileNotFound stubFileNotFound.settingsPackage to be a stable, predictable identifier for every module in this package. (Actually, I want it *.settingsPackage to be a stable, predictable identifier in every package I make.)
2. In this package (and in most packages), I want it to be a "private" identifier.
3. Use well-formed Python.

unused-import (F401)

The advice on the F401 page doesn't seem to apply to my situation, so I suspect that I ought to be using a different mechanism to achieve my goals. I read the linked resources, such as Library interface (public and private symbols). If the information I need is in those resources, then I overlooked it.

Your guidance, especially pointing me to paradigms

This precise issue described above is relatively trivial. On the other hand, I believe managing the logical namespace is exceptionally important. I suspect that if I were to better understand this minor issue, then I could better cope with the frustrating #$%&&#$^% Python namespace, you know?

[ntBre]

I'm not sure I totally understand the request here. If you want to suppress F401 in this example, I think you should be able to use:

# __init__.py

from stubFileNotFound._theSSOT import settingsPackage as settingsPackage

or

# __init__.py

from stubFileNotFound._theSSOT import settingsPackage

__all__ = ["settingsPackage"]

Are those the pieces of advice in the docs that don't seem applicable?

I think if you want to indicate that it's part of a private API, you would name it something like _settingsPackage with a leading underscore, and then follow one of the other F401 suggestions. But again I may be missing part of the constraints here.

[hunterhogan]

I think I know how to efficiently organize the "public" namespace, such as with the two methods you described:

• "re-exporting" using as
• __all__

I think I know how to exclude identifiers from the public namespace, including by:

• not re-exporting using as
• not using from Y import *
• not adding to __all__
• using an identifier that starts with an underscore

However, I don't know any strategies or tactics for efficiently managing my "private" namespace.

(I don't have professional training or experience as a programmer, so, for example, I might misuse technical terms.)

Forced ignorance = dependable namespace

My approaches to organization might be described as "separation of concerns" or "domain-driven design" or functions should be "agnostic" of XYZ, but I don't think those are accurate. More accurate: the accountant never pours the concrete, and only the accountant handles the money. Furthermore, I don't want agnostic APIs: I want to enforce ignorance of everything behind the API.

That applies to the private namespace. I want the entire package to use the identifier stubFileNotFound.settingsPackage, and I want the flexibility to move the identifier into a different module. Furthermore, I am strongly opposed to two Python conventions: the CAPSLOCK fairy and the underscore invisibility cloak. Most of the time, settingsPackage is private in my packages, but in some packages, it is a critical public identifier. Changing it to _settingsPackage is the same as not wearing pants during a business video-conference: "It's ok because no one will ever know."

More complex example

Again, settingsPackage is inherently trivial, so I'll try to give a complex example. This example is from code I don't use anymore, and I'm not trying to fix it.

I was using pathlib to manage file operations, but had to change to filesystem2. Despite using separation-of-concerns, it was extremely difficult to realign all identifiers in the package.

logistics.py

from fs import open_fs, path as fs_path
from fs.walk import Walker
from logisticsVariables import (
	dictionary_dataset_type, dictionaryDatasetPrefixes, dictionaryPrefixDatasets, fileExtension, fractionTypesDataset,
	pathsStorageAccounts, setDatasetTypes, setFractionTypes, subPath, subPathEmailSubPath, subPathsStorageAccounts, zPath)
from typesSubmissions import DecodedFilename, fs2Path
...

def archivistEncodesAlgorithmInPath(algorithm: str) -> str:
def archivistEncodesJobInPath( dictionaryJobs: JobsSeries | DictionaryJobs | SingleJob | JobDownloadFractions | dict[str, Any] = {}, submissionDatasetType: str | None = None, algorithm: str | None = None, mutations: Sequence[Callable] | Sequence[str] = [] ) -> fs2Path:
def archivistFormatsFileNumber(fileNumber: Any) -> str:
def archivistMakesListFilenames( dictionaryJobs: JobsSeries | DictionaryJobs | None = None, datasetPrefix: str | None = None, listFileNumbers: list[int] | None = None, listFractionTypes: list[str] | None = None, fileExtension: str | None = None, submissionDatasetType: str | None = None, ) -> list[str]:
def archivistMakesListPathsSearch(listRelativePaths: Sequence[fs2Path], listPathsRoot: Sequence[fs2Path] | None = None) -> list[fs2Path]:
def archivistMakesListRelativePaths(jobsSeries: JobsSeries) -> list[fs2Path]:
def librarianConvertsToGoogleDriveFS(pathTarget: fs2Path) -> fs2Path:
def librarianDecodesFilename(filename: str) -> DecodedFilename:
def librarianDecodesPathToAlgorithm(directory: str) -> str:
def librarianOrganizesByFilename( listPathFilenames: Sequence[fs2Path], listFilenames: Collection[str] | None = None, ) -> dict[str, list[fs2Path]]:
def valetGetsFiles(listAbsolutePaths: list[fs2Path], listFilenames: list[str]) -> list[fs2Path]:
def valetGetsWAV(pathsWAV: fs2Path | list[fs2Path] | None = None, recursive: bool | None = True, fileExtension: str | None = '.wav') -> list[fs2Path]:
def valetOutfitsWAVsSolid(dictionaryJobs: JobsSeries | DictionaryJobs | None = None, *, solidFractionType: str | None = None, pathSolid: fs2Path | None = None, filePrefix: str | None = None, listFileNumbers: list[int] | None = None, fileExtension: str | None = None) -> list[fs2Path]:
def Z0Z_librarianTruncatesToRelativePathModel(pathTarget: fs2Path, includeShortcutPath: bool = False) -> fs2Path:

logisticsVariables.py

from typesSubmissions import fs2Path
import fs
import tempfile

zPath: dict[str, fs2Path] = {}

zPath.update({
	# 3 paths
})

zPath.update({
	# 10 paths
})

zPath.update({
	# 2 paths
})

subPathEmailSubPath.update({value: key for key, value in subPathEmailSubPath.items()})

for subPath in subPathsStorageAccounts:
	# 6 total paths
	zPath[subPath] = ...

fileExtension = '.wav'

manageGoogleDrives.py

from google.auth.external_account_authorized_user import Credentials
from google.auth.transport.requests import Request as GoogleRequest
from google.oauth2.credentials import Credentials as GoogleCredentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build as GoogleBuildAPI
from logistics import librarianConvertsToGoogleDriveFS, pathsStorageAccounts, subPathEmailSubPath, zPath
from typesSubmissions import fs2Path
from fs import open_fs  # noqa: E402
from fs import path as fs_path  # noqa: E402
from fs.googledrivefs.googledrivefs import GoogleDriveFS  # noqa: E402

pathCredentialsGoogleDrive = zPath['manageGoogleDrives']
pathFilenameClientSecret = fs_path.combine(pathCredentialsGoogleDrive, filenameClientSecret)
pathFilenameApprovedUsers = fs_path.combine(pathCredentialsGoogleDrive, filenameApprovedUsers)
pathAuthenticationTokens = fs_path.combine(pathCredentialsGoogleDrive, 'authenticationTokens')
...

def deleteBatchGoogleFilesByID(dictionaryGoogleDriveServices: dict[str, Any], dictionaryOwnersFileId):
def deleteGoogleFiles(listPathFilenames: list[fs2Path]):
def findOwnersAndId(dictionaryEmailsListPathFilenames: dict[str, list[fs2Path]], dictionaryCredentialsGoogleDrive) -> dict[str, list[str]]:
def getDictionaryOwnersFileId(listPathFilenames: list[fs2Path]) -> dict[str, list[str]]:
def initializeGoogleDriveServices(getCredentials: bool = False):

oh. em. gee. Going through those files was traumatic.

I have learned a lot since then, but I have not learned strategies or paradigms for managing the internal namespace of a complex package.