feat!: resolve credentials from env vars or memory, never write files

CredentialManager resolves credentials from memory, an existing file
(read-only), the OSW_USERNAME/OSW_PASSWORD environment variables (e.g.
via .env), or an interactive prompt, and no longer persists them:
OswExpress drops the save-path prompt and auto-save, the prompt result
stays in memory, save_credentials_to_file becomes an explicit
deprecated opt-in and stops editing .gitignore. Update tests to the
new contract and document the resolution order.

Also keep the entity model pristine after tests and clean up warnings:
snapshot and restore src/osw/model/entity.py around integration test
sessions (fetch_schema regenerates it into the source tree by design),
remove a self-referential deprecation on StoreOntologiesParam, make
FileResult.close() a silent no-op on closed files like io streams,
mark deliberately triggered warnings as expected per test, and filter
non-actionable third-party warnings narrowly (122 -> 1 on the
integration suite).

BREAKING CHANGE: credentials are no longer written to disk
automatically; rely on OSW_USERNAME/OSW_PASSWORD (or a .env file), an
in-memory CredentialManager, or a self-managed credentials file.

Author: raederan

docs/api/auth.md

@@ -1,5 +1,14 @@
 # Authentication
 
-Credential handling for wiki and service logins.
+Credential handling for wiki and service logins. Credentials are resolved
+in this order and held in memory only:
+
+1. Credentials added programmatically (`add_credential`)
+2. An existing credentials file (read-only, if one is configured)
+3. The environment variables `OSW_USERNAME` / `OSW_PASSWORD`
+   (`OSL_*` variants work too), e.g. loaded from a `.env` file
+4. An interactive prompt (fallback `ask`)
+
+The library never writes credentials to disk on its own.
 
 ::: osw.auth.CredentialManager

docs/get-started.md

@@ -59,8 +59,10 @@ instances = osw.site.semantic_search("[[Category:Item]]")
 print(instances)
 ```
 
-Credentials are prompted for interactively or read from a credentials file;
-see [Authentication](api/auth.md).
+Credentials are resolved from the environment variables `OSW_USERNAME` /
+`OSW_PASSWORD` (e.g. loaded from a `.env` file), from an existing
+credentials file, or via an interactive prompt - and are held in memory
+only, never written to disk; see [Authentication](api/auth.md).
 
 ## Examples and tutorials
 

pyproject.toml

@@ -135,6 +135,28 @@ testpaths = ["tests"]
 addopts = "--cov --cov-config=pyproject.toml --cov-report=term-missing --ignore=tests/integration"
 norecursedirs = ["dist", "build", ".tox"]
 asyncio_default_fixture_loop_scope = "function"
+# Third-party warnings that are not actionable in this repo. Everything
+# emitted by our own code is either fixed or explicitly expected via
+# per-test filterwarnings markers.
+# KNOWN RESIDUAL: a handful of pydantic class-based-config deprecations
+# from oold/prefect are emitted at import time under state that no pytest
+# or interpreter filter reaches; they still show up in the summary.
+filterwarnings = [
+    # oold still uses pydantic-v1-style class-based Config (pydantic v2 deprecation)
+    "ignore:Support for class-based `config` is deprecated:DeprecationWarning",
+    # prefect 2.x internals: pydantic v2 deprecations and vendored starlette
+    "ignore:The `__fields__` attribute is deprecated:DeprecationWarning",
+    "ignore:The `__fields_set__` attribute is deprecated:DeprecationWarning",
+    "ignore:The private method `_iter` will be removed:DeprecationWarning",
+    "ignore:Please use `import python_multipart` instead:PendingDeprecationWarning",
+    # sqlalchemy reflection notes from the prefect test harness
+    "ignore:Skipped unsupported reflection",
+    # datamodel-code-generator does not know OSW's custom JSON-schema formats
+    "ignore:format of '.*' not understood:UserWarning",
+    # rdflib internals
+    "ignore:Dataset.default_context is deprecated:DeprecationWarning",
+    "ignore:ConjunctiveGraph is deprecated:DeprecationWarning",
+]
 
 [tool.coverage.run]
 branch = true

src/osw/auth.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
 import getpass
+import os
+import warnings
 from enum import Enum
 from pathlib import Path
 from typing import List, Optional, Union
@@ -160,6 +162,17 @@ def get_credential(self, config: CredentialConfig) -> BaseCredential:
                 return match
             return self._oold_to_osw(match)
 
+        # Environment variables (e.g. loaded from a .env file) come before
+        # any interactive fallback; credentials are kept in memory only.
+        username = os.getenv("OSW_USERNAME") or os.getenv("OSL_USERNAME")
+        password = os.getenv("OSW_PASSWORD") or os.getenv("OSL_PASSWORD")
+        if username is not None and password is not None:
+            cred = CredentialManager.UserPwdCredential(
+                username=username, password=password, iri=config.iri
+            )
+            self.add_credential(cred)
+            return cred
+
         if config.fallback is CredentialManager.CredentialFallback.ask:
             if self.cred_filepath:
                 filepath_str = "', '".join([str(fp) for fp in self.cred_filepath])
@@ -172,9 +185,9 @@ def get_credential(self, config: CredentialConfig) -> BaseCredential:
             cred = CredentialManager.UserPwdCredential(
                 username=username, password=password, iri=config.iri
             )
+            # kept in memory only; persisting credentials to a file happens
+            # exclusively through an explicit save_credentials_to_file() call
             self.add_credential(cred)
-            if self.cred_filepath:
-                self.save_credentials_to_file()
             return cred
 
         return None
@@ -250,6 +263,13 @@ def save_credentials_to_file(
             If True, the cred_filepath is set to the given filepath. If False, the
             cred_filepath of the CredentialManager is not changed.
         """
+        warnings.warn(
+            "save_credentials_to_file() writes credentials to disk in clear "
+            "text and is deprecated. Prefer environment variables (e.g. via "
+            "a .env file) or in-memory credentials.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         cred_filepaths = [filepath]
         if filepath is None:
             cred_filepaths = self.cred_filepath
@@ -276,65 +296,5 @@ def save_credentials_to_file(
             else:
                 print(f"Credentials file created at '{fp.resolve()}'.")
 
-        # Creating or updating .gitignore file in the working directory
-        cwd = Path.cwd()
-        potential_fp = [
-            cwd / ".gitignore",
-            cwd.parent / ".gitignore",
-        ]
-        gitignore_fp = potential_fp[0]
-        # Stops if a .gitignore file is found
-        for fp in potential_fp:
-            if fp.exists():
-                gitignore_fp = fp
-                break
-        # Creates a .gitignore file if none is found
-        if not gitignore_fp.exists():
-            if not gitignore_fp.parent.exists():
-                gitignore_fp.parent.mkdir(parents=True)
-            gitignore_fp.touch()
-        # Reads the .gitignore file
-        with open(gitignore_fp) as stream:
-            content = stream.read()
-        comment_set = False
-        osw_dir_added = False
-        # For every file path in the list of credentials file paths
-        for _ii, fp in enumerate(cred_filepaths):
-            if default_paths.osw_files_dir in fp.parents and not osw_dir_added:
-                msg = (
-                    f"Adding '{default_paths.osw_files_dir}' to gitignore file "
-                    f"'{gitignore_fp}'."
-                )
-                containing_gitignore = gitignore_fp.parent.absolute()
-                if containing_gitignore in default_paths.osw_files_dir.parents:
-                    # If the default_path.osw_files_dir is a subdirectory of the directory
-                    # containing the .gitignore file, add the relative path to the
-                    # .gitignore file
-                    rel = default_paths.osw_files_dir.relative_to(containing_gitignore)
-                    to_add = f"\n*/{rel.as_posix()!s}/*"
-                else:
-                    # Test if the default_path.osw_files_dir is a subdirectory of the
-                    # directory containing the .gitignore file
-                    to_add = (
-                        f"\n*/{default_paths.osw_files_dir.absolute().as_posix()}/*"
-                    )
-                osw_dir_added = True
-            else:
-                msg = f"Adding '{fp.name}' to gitignore file '{gitignore_fp}'."
-                to_add = f"\n*/{fp.name}"
-            if not to_add or to_add in content:
-                continue
-            print(msg)
-            with open(gitignore_fp, "a") as stream:
-                # Only add comment if not already set
-                comment = (
-                    "\n# Automatically added by osw.auth.CredentialManager."
-                    "save_credentials_to_file:"
-                )
-                if not comment_set and comment not in content:
-                    stream.write(comment)
-                    comment_set = True
-                stream.write(to_add)
-
 
 CredentialManager.CredentialConfig.update_forward_refs()

src/osw/defaults.py

@@ -120,9 +120,10 @@ def update_attr(set_attr, to_update, old_val, new_val):
                     old_rel_path = getattr(self, attr_name).relative_to(old_val)
                     new_rel_path = new_val / old_rel_path
                     setattr(self, attr_name, new_rel_path)
+                    cls_name = type(self).__name__
                     print(
-                        f"Following the setting of {self.__name__}.{set_attr}, "
-                        f"{self.__name__}.{attr_name} was updated to {new_rel_path}."
+                        f"Following the setting of {cls_name}.{set_attr}, "
+                        f"{cls_name}.{attr_name} was updated to {new_rel_path}."
                     )
 
         if attr_name == "base":

src/osw/express.py

@@ -112,55 +112,31 @@ def __init__(
             # If a credential manager is explicitly defined, that should have priority
             cred_filepath = cred_mngr.cred_filepath[0]
         if cred_filepath is None:
-            # If no credential file path is given, try to take it from environment vars
+            # If no credential file path is given, try to take it from environment
+            # vars. A credential file is only ever READ; credentials obtained from
+            # environment variables (OSW_USERNAME/OSW_PASSWORD, e.g. loaded from a
+            # .env file) or an interactive prompt are kept in memory only.
             if os.getenv("OSW_CRED_FILEPATH") is not None:
                 cred_filepath = os.getenv("OSW_CRED_FILEPATH")
             elif os.getenv("OSL_CRED_FILEPATH") is not None:
                 cred_filepath = os.getenv("OSL_CRED_FILEPATH")
-            else:
-                # Otherwise, prompt user to set cred_filepath
-                cred_filepath = input(
-                    "No credential file path was provided. Please specify, where to "
-                    "save the credential file: "
-                )
+        if cred_filepath is not None:
+            if not isinstance(cred_filepath, Path):
+                cred_filepath = Path(cred_filepath)
+            if not cred_filepath.is_file():
                 print(
-                    f"Credential file path changed to '{cred_filepath}'."
-                    "\nPlease set environment variable 'OSW_CRED_FILEPATH' accordingly."
-                    "\nIf adequate, make sure to load the .env file."
+                    f"Credential file '{cred_filepath}' does not exist and will "
+                    "be ignored. Credentials are taken from the environment "
+                    "variables OSW_USERNAME/OSW_PASSWORD or an interactive "
+                    "prompt instead (in-memory only)."
                 )
-        if not isinstance(cred_filepath, Path):
-            cred_filepath = Path(cred_filepath)
-        if not cred_filepath.is_file():
-            print(f"Credential file '{cred_filepath}' is not a file. ")
-        if not cred_filepath.exists():
-            print(
-                f"Credential file '{cred_filepath}' does not exist and will be created."
-            )
+                cred_filepath = None
         if cred_mngr is None:
             # Create a credentials manager
             if cred_filepath is None:
                 cred_mngr = CredentialManager()
             else:  # Reuse passed cred_filepath
                 cred_mngr = CredentialManager(cred_filepath=cred_filepath)
-        if not cred_mngr.iri_in_file(domain):
-            cred = cred_mngr.get_credential(
-                CredentialManager.CredentialConfig(
-                    iri=domain,
-                    fallback=CredentialManager.CredentialFallback.ask,
-                )
-            )
-            cred_mngr.add_credential(cred)
-            # If there was no cred_filepath specified within the CredentialManager
-            #  the filepath from the OswExpress constructor will be used (either passed
-            #  as argument or set by default)
-            if cred_mngr.cred_filepath is None:
-                cred_mngr.save_credentials_to_file(
-                    filepath=cred_filepath, set_cred_filepath=True
-                )
-            # If there was a cred_filepath specified within the CredentialManager,
-            #  that filepath will be used
-            else:
-                cred_mngr.save_credentials_to_file()
         # Test if domain is reachable
         try:
             url = f"https://{domain}/wiki/Main_Page"
@@ -358,10 +334,9 @@ def open(self, mode: str = None, **kwargs) -> TextIO:
         return self.file_io
 
     def close(self) -> None:
-        """Close the file, if not already closed."""
-        if self.file_io is None or self.file_io.closed:
-            warn("File already closed or not opened.")
-        else:
+        """Close the file. Like io streams, closing an already closed (or
+        never opened) file is a silent no-op."""
+        if self.file_io is not None and not self.file_io.closed:
             self.file_io.close()
 
     def read(self, n: int = -1) -> AnyStr:

src/osw/ontology.py

@@ -8,7 +8,6 @@
 from pydantic.v1 import PrivateAttr
 from pyld import jsonld
 from rdflib import Graph
-from typing_extensions import deprecated
 
 from osw.core import OSW, model
 from osw.utils.strings import camel_case, pascal_case
@@ -832,7 +831,6 @@ def _store_ontology(self, param: StoreOntologyParam):
             )
         )
 
-    @deprecated("use ontology.OntologyImporter.StoreOntologiesParam instead")
     class StoreOntologiesParam(model.OswBaseModel):
         entities: Optional[List[model.OswBaseModel]]
         """If we use model.Entity here, all instances are casted to model.Entity

tests/integration/conftest.py

@@ -0,0 +1,53 @@
+"""Working-directory isolation for the integration tests.
+
+The tests and the library defaults create files relative to the current
+working directory - among them credential files in CLEAR TEXT
+(accounts.pwd.yaml and domain-named files) and download caches
+(osw_files/). Running each test in its own pytest tmp dir keeps all of
+that out of the repository tree; pytest cleans its tmp dirs up on its
+own. Never rely on .gitignore for credential artifacts.
+"""
+
+from pathlib import Path
+
+import pytest
+
+import osw.model.entity
+from osw.defaults import paths as default_paths
+
+
+@pytest.fixture(autouse=True, scope="session")
+def _restore_entity_model():
+    """Snapshot and restore src/osw/model/entity.py around the test session.
+
+    OSW.fetch_schema regenerates the entity model INTO THE INSTALLED
+    PACKAGE by design, which in an editable install is the source tree.
+    Restoring the pre-session content keeps the working tree clean after
+    `make test-integration` without relying on git or .gitignore.
+    """
+    model_file = Path(osw.model.entity.__file__)
+    snapshot = model_file.read_bytes()
+    yield
+    if model_file.read_bytes() != snapshot:
+        model_file.write_bytes(snapshot)
+        print(f"\nRestored pre-session state of '{model_file}'.")
+
+
+@pytest.fixture(autouse=True)
+def _isolate_working_dir(tmp_path, monkeypatch):
+    # covers every Path.cwd()-relative write in the tests themselves
+    monkeypatch.chdir(tmp_path)
+    # osw.defaults captures Path.cwd() at import time, so the singleton
+    # still points into the repo; re-base it for the duration of the
+    # test (setting `base` cascades to the dependent paths) and restore
+    # the previous values afterwards.
+    old = {
+        "base": default_paths.base,
+        "osw_files_dir": default_paths.osw_files_dir,
+        "cred_filepath": default_paths.cred_filepath,
+        "download_dir": default_paths.download_dir,
+    }
+    default_paths.base = tmp_path
+    yield
+    for name, value in old.items():
+        setattr(default_paths, name, value)

tests/integration/ontology_import_test.py

@@ -11,7 +11,7 @@
 # uv run pytest tests/integration -o addopts="" --wiki_domain domain --wiki_username user --wiki_password pass
 
 
-def test_ontology_import(wiki_domain, wiki_username, wiki_password):
+def test_ontology_import(wiki_domain, wiki_username, wiki_password, tmp_path):
     cm = CredentialManager()
     cm.add_credential(
         CredentialManager.UserPwdCredential(
@@ -62,7 +62,8 @@ def test_ontology_import(wiki_domain, wiki_username, wiki_password):
         base_class=model.OwlClass,
         base_class_title="Category:OSW725a3cf5458f4daea86615fcbd0029f8",  # OwlClass
         dump_files=True,
-        dump_path=os.path.dirname(os.path.abspath(__file__)),
+        # dump into the pytest tmp dir, not the module directory
+        dump_path=str(tmp_path),
         dry_run=False,
     )