Merge pull request #2 from dropbox/master

Reset

Author: mehdigmira

.travis.yml

@@ -17,7 +17,7 @@ jobs:
     script: |
       set -e
       pytest
-  - name: "run direct typecheck"
+  - name: "run typecheck on stubs"
     python: 3.6
     script: |
       set -e
@@ -29,6 +29,11 @@ jobs:
     python: 3.6
     script: |
       flake8 sqlalchemy-stubs
+  - name: "run typecheck on plugin"
+    python: 3.6
+    script: |
+      set -e
+      MYPYPATH=external/mypy python3 -m mypy --disallow-untyped-defs sqlmypy.py
 
 
 before_install: |

README.md

@@ -6,14 +6,14 @@ Mypy plugin and stubs for SQLAlchemy
 [![Build Status](https://travis-ci.org/dropbox/sqlalchemy-stubs.svg?branch=master)](https://travis-ci.org/dropbox/sqlalchemy-stubs)
 [![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
 
-This package contains [type stubs](https://www.python.org/dev/peps/pep-0561/) and soon a
-mypy plugin to provide more precise static types
-and type inference for [SQLAlchemy framework](http://docs.sqlalchemy.org/en/latest/).
-SQLAlchemy uses some Python "magic" that
-makes having precise types for some code patterns problematic. This is why we need to
-accompany the stubs with mypy plugins. The final goal is to be able to get precise types
-for most common patterns. A simple example:
-
+This package contains [type stubs](https://www.python.org/dev/peps/pep-0561/) and a
+[mypy plugin](https://mypy.readthedocs.io/en/latest/extending_mypy.html#extending-mypy-using-plugins)
+to provide more precise static types and type inference for
+[SQLAlchemy framework](http://docs.sqlalchemy.org/en/latest/). SQLAlchemy uses some
+Python "magic" that makes having precise types for some code patterns problematic.
+This is why we need to accompany the stubs with mypy plugins. The final goal is to
+be able to get precise types for most common patterns. Currently, basic operations
+with models are supported. A simple example:
 ```python
 from sqlalchemy.ext.declarative import declarative_base
 from sqlalchemy import Column, Integer, String
@@ -25,11 +25,33 @@ class User(Base):
     id = Column(Integer, primary_key=True)
     name = Column(String)
 
-user: User
+user = User(id=42, name=42)  # Error: Incompatible type for "name" of "User"
+                             # (got "int", expected "Optional[str]"
 user.id  # Inferred type is "int"
-User.name  # Inferred type is "Column[str]"
+User.name  # Inferred type is "Column[Optional[str]]"
+```
+
+Some auto-generated attributes are added to models. Simple relationships
+are supported but require models to be imported:
+```python
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from models.address import Address
+
+...
+
+class User(Base):
+    __tablename__ = 'users'
+    id = Column(Integer, primary_key=True)
+    name = Column(String)
+    address = relationship('Address')  # OK, mypy understands string references.
 ```
 
+The next step is to support precise types for table definitions (e.g.
+inferring `Column[Optional[str]]` for `users.c.name`, currently it is just
+`Column[Any]`), and precise types for results of queries made using `query()`
+and `select()`.
+
 ## Installation
 
 To install the latest version of the package:
@@ -45,6 +67,12 @@ stable version as:
 pip install -U sqlalchemy-stubs
 ```
 
+*Important*: you need to enable the plugin in your mypy config file:
+```
+[mypy]
+plugins = sqlmypy
+```
+
 ## Development Setup
 
 First, clone the repo and cd into it, like in _Installation_, then:

sqlalchemy-stubs/engine/interfaces.pyi

@@ -4,6 +4,8 @@ from .result import ResultProxy
 from ..sql.compiler import Compiled as Compiled, TypeCompiler as TypeCompiler
 
 class Dialect(object):
+    @property
+    def name(self) -> str: ...
     def create_connect_args(self, url): ...
     @classmethod
     def type_descriptor(cls, typeobj): ...

sqlalchemy-stubs/sql/schema.pyi

@@ -11,6 +11,7 @@ from .. import util
 from ..engine import Engine, Connection, Connectable
 from ..engine.url import URL
 from .compiler import DDLCompiler
+from .expression import FunctionElement
 import threading
 
 _T = TypeVar('_T')
@@ -90,25 +91,25 @@ class Column(SchemaItem, ColumnClause[_T]):
     def __init__(self, name: str, type_: Type[TypeEngine[_T]], *args: Any, autoincrement: Union[bool, str] = ...,
                  default: Any = ..., doc: str = ..., key: str = ..., index: bool = ..., info: Mapping[str, Any] = ...,
                  nullable: bool = ..., onupdate: Any = ..., primary_key: bool = ..., server_default: Any = ...,
-                 server_onupdate: FetchedValue = ..., quote: Optional[bool] = ..., unique: bool = ...,
+                 server_onupdate: Union[FetchedValue, FunctionElement] = ..., quote: Optional[bool] = ..., unique: bool = ...,
                  system: bool = ..., comment: str = ...) -> None: ...
     @overload
     def __init__(self, type_: Type[TypeEngine[_T]], *args: Any, autoincrement: Union[bool, str] = ...,
                  default: Any = ..., doc: str = ..., key: str = ..., index: bool = ..., info: Mapping[str, Any] = ...,
                  nullable: bool = ..., onupdate: Any = ..., primary_key: bool = ..., server_default: Any = ...,
-                 server_onupdate: FetchedValue = ..., quote: Optional[bool] = ..., unique: bool = ...,
+                 server_onupdate: Union[FetchedValue, FunctionElement] = ..., quote: Optional[bool] = ..., unique: bool = ...,
                  system: bool = ..., comment: str = ...) -> None: ...
     @overload
     def __init__(self, name: str, type_: TypeEngine[_T], *args: Any, autoincrement: Union[bool, str] = ...,
                  default: Any = ..., doc: str = ..., key: str = ..., index: bool = ..., info: Mapping[str, Any] = ...,
                  nullable: bool = ..., onupdate: Any = ..., primary_key: bool = ..., server_default: Any = ...,
-                 server_onupdate: FetchedValue = ..., quote: Optional[bool] = ..., unique: bool = ...,
+                 server_onupdate: Union[FetchedValue, FunctionElement] = ..., quote: Optional[bool] = ..., unique: bool = ...,
                  system: bool = ..., comment: str = ...) -> None: ...
     @overload
     def __init__(self, type_: TypeEngine[_T], *args: Any, autoincrement: Union[bool, str] = ...,
                  default: Any = ..., doc: str = ..., key: str = ..., index: bool = ..., info: Mapping[str, Any] = ...,
                  nullable: bool = ..., onupdate: Any = ..., primary_key: bool = ..., server_default: Any = ...,
-                 server_onupdate: FetchedValue = ..., quote: Optional[bool] = ..., unique: bool = ...,
+                 server_onupdate: Union[FetchedValue, FunctionElement] = ..., quote: Optional[bool] = ..., unique: bool = ...,
                  system: bool = ..., comment: str = ...) -> None: ...
     def references(self, column: Column[Any]) -> bool: ...
     def append_foreign_key(self, fk: ForeignKey) -> None: ...
@@ -260,7 +261,7 @@ class ForeignKeyConstraint(ColumnCollectionConstraint):
     use_alter: bool = ...
     match: Optional[str] = ...
     elements: List[ForeignKey] = ...
-    def __init__(self, columns: Sequence[str], refcolumns: Sequence[Union[str, Column[Any]]], name: Optional[str] = ...,
+    def __init__(self, columns: SequenceType[str], refcolumns: SequenceType[Union[str, Column[Any]]], name: Optional[str] = ...,
                  onupdate: Optional[str] = ..., ondelete: Optional[str] = ..., deferrable: Optional[bool] = ...,
                  initially: Optional[str] = ..., use_alter: bool = ..., link_to_name: bool = ..., match: Optional[str] = ...,
                  table: Optional[Table] = ..., info: Optional[Mapping[str, Any]] = ..., **dialect_kw: Any) -> None: ...
@@ -325,12 +326,12 @@ class MetaData(SchemaItem):
     @property
     def sorted_tables(self) -> List[Table]: ...
     def reflect(self, bind: Optional[Connectable] = ..., schema: Optional[str] = ..., views: bool = ...,
-                only: Optional[Union[Sequence[str], Callable[[str, MetaData], bool]]] = ..., extend_existing: bool = ...,
+                only: Optional[Union[SequenceType[str], Callable[[str, MetaData], bool]]] = ..., extend_existing: bool = ...,
                 autoload_replace: bool = ..., **dialect_kwargs: Any) -> None: ...
     def append_ddl_listener(self, event_name: str, listener: Callable[[str, MetaData, Connection], None]) -> None: ...
-    def create_all(self, bind: Optional[Connectable] = ..., tables: Optional[Sequence[Table]] = ...,
+    def create_all(self, bind: Optional[Connectable] = ..., tables: Optional[SequenceType[Table]] = ...,
                    checkfirst: bool = ...) -> None: ...
-    def drop_all(self, bind: Optional[Connectable] = ..., tables: Optional[Sequence[Table]] = ...,
+    def drop_all(self, bind: Optional[Connectable] = ..., tables: Optional[SequenceType[Table]] = ...,
                  checkfirst: bool = ...) -> None: ...
 
 class ThreadLocalMetaData(MetaData):

sqlalchemy-stubs/sql/type_api.pyi

@@ -1,4 +1,4 @@
-from typing import Any, Optional, Union, TypeVar, Generic, Type, Callable, ClassVar, Tuple, Mapping, overload
+from typing import Any, Optional, Union, TypeVar, Generic, Type, Callable, ClassVar, Tuple, Mapping, overload, Text as typing_Text
 from .. import util
 from .visitors import Visitable as Visitable, VisitableType as VisitableType
 from .base import SchemaEventTarget as SchemaEventTarget
@@ -91,7 +91,7 @@ class TypeDecorator(SchemaEventTarget, TypeEngine[_T]):
     def load_dialect_impl(self, dialect: Dialect) -> TypeEngine[Any]: ...
     def __getattr__(self, key: str) -> Any: ...
     def process_literal_param(self, value: Optional[_T], dialect: Dialect) -> Optional[str]: ...
-    def process_bind_param(self, value: Optional[_T], dialect: Dialect) -> Optional[str]: ...
+    def process_bind_param(self, value: Optional[_T], dialect: Dialect) -> Optional[typing_Text]: ...
     def process_result_value(self, value: Optional[Any], dialect: Dialect) -> Optional[_T]: ...
     def literal_processor(self, dialect: Dialect) -> Callable[[Optional[_T]], Optional[str]]: ...
     def bind_processor(self, dialect: Dialect) -> Callable[[Optional[_T]], Optional[str]]: ...