Fix mypy issues related to ObjectStoragePath in main branch

[tatiana]

The solution utilises forward references (string literals) for the ObjectStoragePath type, allowing mypy to understand the types without requiring the actual class to be available at runtime. This is the standard approach for handling optional dependencies in type annotations.

Cosmos' main branch is red due to mypy checks failing, as observed in this sample GitHub Actions job:
https://github.com/astronomer/astronomer-cosmos/actions/runs/18122118077/job/51706664314

mypy-python..............................................................Failed
- hook id: mypy
- exit code: 1

cosmos/cache.py:76: error: Incompatible types in assignment (expression has type "ObjectStoragePath", variable has type "Path | None")  [assignment]
cosmos/cache.py:78: error: Item "None" of "Path | None" has no attribute "exists"  [union-attr]
cosmos/cache.py:78: note: Error code "union-attr" not covered by "type: ignore" comment
cosmos/cache.py:80: error: Item "None" of "Path | None" has no attribute "mkdir"  [union-attr]
cosmos/config.py:233: error: Incompatible types in assignment (expression has type "ObjectStoragePath", variable has type "Path | None")  [assignment]
cosmos/operators/local.py:325: error: Incompatible return value type (got "tuple[ObjectStoragePath, str]", expected "tuple[Path, str] | tuple[None, None]")  [return-value]
Found 5 errors in 3 files (checked 35 source files)

The same job was working without failures two days ago:
https://github.com/astronomer/astronomer-cosmos/actions/runs/18111649257/job/51539065565

Changes introduced

• Added TYPE_CHECKING imports: Added conditional imports for ObjectStoragePath in all affected files using the TYPE_CHECKING pattern to avoid runtime import errors when the class is not available.
• Updated type annotations: Used string literals (forward references) for ObjectStoragePath in type annotations to avoid mypy errors:

  Path | "ObjectStoragePath" | None instead of Path | ObjectStoragePath | None

Fixed specific issues:

• cache.py: Updated _configured_cache_dir variable and _configure_remote_cache_dir() function return type
• config.py: Updated manifest_path field and mandatory_paths dictionary type annotations
• operators/local.py: Updated _configure_remote_target_path() return type and _construct_dest_file_path() parameter type
• dbt/graph.py: Updated _get_dbt_ls_remote_cache() parameter type

Verification

I used the same command as the CI to confirm that the introduced changes fix the original issue:

hatch run tests.py3.10-2.10-1.9:type-check
mypy-python..............................................................Passed

And I also confirmed in the CI:

https://github.com/astronomer/astronomer-cosmos/actions/runs/18167212785/job/51712529044?pr=2012

[netlify]

✅ Deploy Preview for sunny-pastelito-5ecb04 canceled.

Name	Link
🔨 Latest commit	6774903
🔍 Latest deploy log	https://app.netlify.com/projects/sunny-pastelito-5ecb04/deploys/68dd67cb88cde20008739bcb

[Copilot]

Pull Request Overview

This PR fixes mypy type checking issues that were causing CI failures on the main branch. The errors were related to incompatible type assignments involving ObjectStoragePath from Airflow's I/O module.

• Updated type annotations to use forward references for ObjectStoragePath to handle optional dependencies
• Added conditional imports using TYPE_CHECKING pattern to avoid runtime import errors
• Fixed specific type annotation issues in cache, config, and operator modules

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 7 comments.

File	Description
cosmos/operators/local.py	Added conditional import and updated return/parameter types for remote path functions
cosmos/dbt/graph.py	Added conditional import and updated parameter type for remote cache function
cosmos/config.py	Added conditional import and updated manifest_path and mandatory_paths type annotations
cosmos/cache.py	Added conditional import and updated return/variable types for remote cache directory configuration

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[corsettigyg]

apart from the import issue with airflow 3.x, everything looks good to me 💯

a possible (and clean fix) would be

from packaging.version import Version
AIRFLOW_VERSION = Version(airflow.__version__)

if AIRFLOW_VERSION >= Version("3.0"):
    try:
        from airflow.sdk import ObjectStoragePath
    except ImportError:
        pass
else:
    try:
        from airflow.io.path import ObjectStoragePath
    except ImportError:
        pass

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.81%. Comparing base (53e1eb9) to head (6774903).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2012   +/-   ##
=======================================
  Coverage   97.80%   97.81%           
=======================================
  Files          87       87           
  Lines        5525     5526    +1     
=======================================
+ Hits         5404     5405    +1     
  Misses        121      121           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.