Merge pull request #138 from treasure-data/type-hint

Introduce type hint

Author: chezou

.github/workflows/pythontest.yml

@@ -20,9 +20,12 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install .
+          pip install ".[dev]"
           pip install -r requirements.txt -r test-requirements.txt
           pip install -U coveralls pyyaml
+      - name: Run pyright
+        run: |
+          pyright tdclient
       - name: Run test
         run: |
           coverage run --source=tdclient -m pytest tdclient/test

.gitignore

@@ -8,10 +8,11 @@
 /.eggs
 /.envrc
 /.tox
-/.venv
+/.venv*
 /build
 /dist
 /tmp
+/.agent
 
 # JetBrains IDE
 .idea/

.pre-commit-config.yaml

@@ -2,22 +2,28 @@
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v2.0.0
+    rev: v6.0.0
     hooks:
     - id: trailing-whitespace
     - id: end-of-file-fixer
     - id: check-yaml
     - id: check-added-large-files
-  - repo: https://github.com/asottile/seed-isort-config
-    rev: v1.9.3
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.2
     hooks:
-    - id: seed-isort-config
-  - repo: https://github.com/pre-commit/mirrors-isort
-    rev: v4.3.21
+      # Run the linter.
+      - id: ruff
+        args: [--fix]
+      # Run the formatter.
+      - id: ruff-format
+  - repo: https://github.com/RobertCraigie/pyright-python
+    rev: v1.1.407
     hooks:
-    - id: isort
-  - repo: https://github.com/python/black
-    rev: stable
-    hooks:
-    - id: black
-      language_version: python3.7
+      - id: pyright
+        exclude: ^docs/
+        additional_dependencies:
+          - msgpack>=0.6.2
+          - urllib3
+          - python-dateutil
+          - typing-extensions>=4.0.0
+          - certifi

README.rst

@@ -255,6 +255,46 @@ which would produce:
   1575454204, "a", "0001", ["a", "b", "c"]
   1575454204, "b", "0002", ["d", "e", "f"]
 
+Type Hints
+----------
+
+td-client-python includes comprehensive type hints (PEP 484) for improved development experience with static type checkers like mypy and pyright. Type hints are available for all public APIs.
+
+**Features:**
+
+
+* Fully typed public API with precise type annotations
+* ``py.typed`` marker file for PEP 561 compliance
+* Type aliases in ``tdclient.types`` for common patterns
+* Support for type checking with mypy, pyright, and other tools
+
+**Example with type checking:**
+
+.. code-block:: python
+
+   import tdclient
+
+   # Type checkers will understand the types
+   with tdclient.Client(apikey="your_api_key") as client:
+       # client is inferred as tdclient.Client
+       job = client.query("sample_db", "SELECT COUNT(1) FROM table", type="presto")
+       # job is inferred as tdclient.models.Job
+       job.wait()
+       for row in job.result():
+           # row is inferred as dict[str, Any]
+           print(row)
+
+**Using type aliases:**
+
+.. code-block:: python
+
+   from tdclient.types import QueryEngineType, Priority
+
+   def run_query(engine: QueryEngineType, priority: Priority) -> None:
+       with tdclient.Client() as client:
+           job = client.query("mydb", "SELECT 1", type=engine, priority=priority)
+           job.wait()
+
 Development
 -----------
 

docs/api/client.rst

@@ -11,5 +11,3 @@ tdclient.client
    :members:
    :undoc-members:
    :show-inheritance:
-
-

docs/conf.py

@@ -78,9 +78,9 @@ def linkcode_resolve(domain, info):
 
 # -- Project information -----------------------------------------------------
 
-project = 'td-client-python'
-copyright = '2019, Arm Treasure Data'
-author = 'Arm Treasure Data'
+project = "td-client-python"
+copyright = "2019, Arm Treasure Data"
+author = "Arm Treasure Data"
 
 # The full version, including alpha/beta/rc tags
 release = pkg_resources.get_distribution(PACKAGE).version
@@ -98,24 +98,24 @@ def linkcode_resolve(domain, info):
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = "sphinx_rtd_theme"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 # html_static_path = ['_static']
 
-autodoc_member_order = 'groupwise'
+autodoc_member_order = "groupwise"

docs/file_import_parameters.rst

@@ -74,7 +74,7 @@ contains ``"not-an-int"``, the resulting ``ValueError`` will not be caught.
 To summarise, the default for reading CSV files is:
 
   ``dialect=csv.excel, encoding="utf-8", columns=None, dtypes=None, converters=None``
-  
+
 TSV data
 --------
 

pyproject.toml

@@ -31,15 +31,19 @@ dependencies = [
   "python-dateutil",
   "msgpack>=0.6.2",
   "urllib3",
+  "typing-extensions>=4.0.0",
 ]
 
 [project.optional-dependencies]
-dev = ["ruff"]
+dev = ["ruff", "pyright"]
 docs = ["sphinx", "sphinx_rtd_theme"]
 
 [tool.setuptools]
 packages = ["tdclient"]
 
+[tool.setuptools.package-data]
+tdclient = ["py.typed"]
+
 [tool.ruff]
 line-length = 88
 
@@ -53,3 +57,19 @@ ignore = ["E203", "E501"]
 
 [tool.ruff.lint.isort]
 known-third-party = ["dateutil","msgpack","pkg_resources","pytest","setuptools","urllib3"]
+
+[tool.pyright]
+include = ["tdclient"]
+exclude = ["**/__pycache__", "tdclient/test", "docs"]
+typeCheckingMode = "basic"
+pythonVersion = "3.9"
+pythonPlatform = "All"
+reportMissingTypeStubs = false
+reportUnknownMemberType = false
+reportUnknownArgumentType = false
+reportUnknownVariableType = false
+reportMissingImports = "warning"
+
+# Pre-commit venv configuration
+venvPath = "."
+venv = ".venv"

tdclient/__init__.py

@@ -1,4 +1,8 @@
+from __future__ import annotations
+
 import datetime
+import time
+from typing import Any
 
 from tdclient import client, connection, errors, version
 
@@ -7,7 +11,7 @@
 Client = client.Client
 
 
-def connect(*args, **kwargs):
+def connect(*args: Any, **kwargs: Any) -> connection.Connection:
     """Returns a DBAPI compatible connection object
 
     Args:
@@ -44,19 +48,19 @@ def connect(*args, **kwargs):
 Timestamp = datetime.datetime
 
 
-def DateFromTicks(ticks):
-    return datetime.date(*datetime.localtime(ticks)[:3])
+def DateFromTicks(ticks: float) -> datetime.date:
+    return datetime.date(*time.localtime(ticks)[:3])
 
 
-def TimeFromTicks(ticks):
-    return datetime.time(*datetime.localtime(ticks)[3:6])
+def TimeFromTicks(ticks: float) -> datetime.time:
+    return datetime.time(*time.localtime(ticks)[3:6])
 
 
-def TimestampFromTicks(ticks):
-    return datetime.datetime(*datetime.localtime(ticks)[:6])
+def TimestampFromTicks(ticks: float) -> datetime.datetime:
+    return datetime.datetime(*time.localtime(ticks)[:6])
 
 
-def Binary(string):
+def Binary(string: bytes) -> bytes:
     return bytes(string)