GH-49103: [Python] Add internal type system stubs (_types, error, _stubs_typing)

[rok]

Rationale for this change

This is the second in series of PRs adding type annotations to pyarrow and resolving #32609. It builds on top of and should be merged after #48618.

What changes are included in this PR?

This adds:

• _types.pyi - Core type definitions including
• _stubs_typing.pyi - Internal typing protocols and helpers used across stub files
• error.pyi - Exception classes (ArrowException, ArrowInvalid, ArrowIOError, etc.)
• Minimal placeholder stubs - lib.pyi, io.pyi, scalar.pyi - using __getattr__ to allow imports to resolve while deferring to subsequent PRs

Are these changes tested?

Via CI type checks established in #48618.

Are there any user-facing changes?

Users will start seeing some minimal annotated types.

• GitHub Issue: [Python] Type checking support #32609
• GitHub Issue: [Python][Annotations] Add internal type system stubs (_types, error, _stubs_typing) #49103

[rok]

I've rebased this on the annotation infra check PR (#48618) to make sure we're on the right track.

[github-actions]

⚠️ GitHub issue #49103 has been automatically assigned in GitHub to PR creator.

[rok]

@dangotbanned I'm about to have limited connectivity for 2 weeks. If you think this is ready we can ask @raulcd to do a last pass and merge, so we get it into the release.

@raulcd I found that I had to do this df7dce5 to get a working editable install. Seems to be due to filename collisions. Thoughts?

[raulcd]

@raulcd I found that I had to do this df7dce5 to get a working editable install. Seems to be due to filename collisions. Thoughts?

What was the error? Seems strange that we have to avoid installing a single specific file (lib) for editable builds

[rok]

The error I was getting without the CMake change was:

>>> import pyarrow
Traceback (most recent call last):
  File "<python-input-0>", line 1, in <module>
    import pyarrow
  File "/Users/rok/Documents/repos/arrow/python/pyarrow/__init__.py", line 59, in <module>
    from pyarrow.lib import (BuildInfo, CppBuildInfo, RuntimeInfo, set_timezone_db_path,
    ...<3 lines>...
                             io_thread_count, is_opentelemetry_enabled, set_io_thread_count)
ModuleNotFoundError: No module named 'pyarrow.lib'

With the CMake change it works fine.

In both cases I'm doing:

export ARROW_HOME=$(pwd)/dist
export CMAKE_PREFIX_PATH=$ARROW_HOME:$CMAKE_PREFIX_PATH
export DYLD_LIBRARY_PATH=$ARROW_HOME/lib:$DYLD_LIBRARY_PATH
uv pip install --no-build-isolation --editable .