Những cách sử dụng tốt cho chú thích chức năng của Python3 Chú thích

Chú thích chức năng: PEP-3107

Tôi đã chạy qua một đoạn mã trình bày các chú thích chức năng của Python3. Khái niệm này đơn giản nhưng tôi không thể nghĩ tại sao chúng được triển khai trong Python3 hoặc bất kỳ cách sử dụng tốt nào cho chúng. Có lẽ SO có thể khai sáng cho tôi?

Làm thế nào nó hoạt động:

def foo(a: 'x', b: 5 + 6, c: list) -> max(2, 9):
    ... function body ...

Mọi thứ theo dấu hai chấm sau một đối số là một 'chú thích' và thông tin theo sau ->là một chú thích cho giá trị trả về của hàm.

foo.func_annotations sẽ trả về một từ điển:

{'a': 'x',
 'b': 11,
 'c': list,
 'return': 9}

Tầm quan trọng của việc có sẵn này là gì?

Tôi nghĩ rằng điều này thực sự tuyệt vời.

Đến từ một nền tảng học thuật, tôi có thể nói với bạn rằng các chú thích đã chứng tỏ bản thân là vô giá khi cho phép các máy phân tích tĩnh thông minh cho các ngôn ngữ như Java. Chẳng hạn, bạn có thể định nghĩa ngữ nghĩa như các hạn chế trạng thái, các luồng được phép truy cập, các giới hạn kiến ​​trúc, v.v., và có khá nhiều công cụ có thể đọc chúng và xử lý chúng để cung cấp các đảm bảo ngoài những gì bạn nhận được từ trình biên dịch. Bạn thậm chí có thể viết những thứ kiểm tra điều kiện tiên quyết / hậu điều kiện.

Tôi cảm thấy một cái gì đó như thế này đặc biệt cần thiết trong Python vì cách gõ yếu hơn, nhưng thực sự không có cấu trúc nào làm cho điều này trở nên đơn giản và là một phần của cú pháp chính thức.

Có những cách sử dụng khác cho các chú thích ngoài sự đảm bảo. Tôi có thể thấy cách tôi có thể áp dụng các công cụ dựa trên Java của mình cho Python. Chẳng hạn, tôi có một công cụ cho phép bạn gán các cảnh báo đặc biệt cho các phương thức và cung cấp cho bạn các chỉ dẫn khi bạn gọi chúng rằng bạn nên đọc tài liệu của chúng (Ví dụ: hãy tưởng tượng bạn có một phương thức không được gọi với giá trị âm, nhưng nó không trực quan từ tên). Với các chú thích, tôi có thể Technicall viết một cái gì đó như thế này cho Python. Tương tự, một công cụ tổ chức các phương thức trong một lớp lớn dựa trên các thẻ có thể được viết nếu có một cú pháp chính thức.

Chú thích chức năng là những gì bạn làm cho chúng.

Chúng có thể được sử dụng cho tài liệu:

def kinetic_energy(mass: 'in kilograms', velocity: 'in meters per second'):
     ...

Chúng có thể được sử dụng để kiểm tra tiền điều kiện:

def validate(func, locals):
    for var, test in func.__annotations__.items():
        value = locals[var]
        msg = 'Var: {0}\tValue: {1}\tTest: {2.__name__}'.format(var, value, test)
        assert test(value), msg


def is_int(x):
    return isinstance(x, int)

def between(lo, hi):
    def _between(x):
            return lo <= x <= hi
    return _between

def f(x: between(3, 10), y: is_int):
    validate(f, locals())
    print(x, y)


>>> f(0, 31.1)
Traceback (most recent call last):
   ... 
AssertionError: Var: y  Value: 31.1 Test: is_int

Ngoài ra, hãy xem http://www.python.org/dev/peps/pep-0362/ để biết cách thực hiện kiểm tra loại.

Đây là một cách trả lời muộn, nhưng AFAICT, cách sử dụng chú thích chức năng tốt nhất hiện nay là PEP-0484 và MyPy .

Mypy là một trình kiểm tra kiểu tĩnh tùy chọn cho Python. Bạn có thể thêm gợi ý loại cho các chương trình Python của mình bằng cách sử dụng tiêu chuẩn sắp tới cho các chú thích loại được giới thiệu trong Python 3.5 beta 1 (PEP 484) và sử dụng mypy để kiểm tra chúng một cách tĩnh.

Được sử dụng như vậy:

from typing import Iterator

def fib(n: int) -> Iterator[int]:
    a, b = 0, 1
    while a < n:
        yield a
        a, b = b, a + b

Chỉ cần thêm một ví dụ cụ thể về việc sử dụng tốt từ câu trả lời của tôi ở đây , kết hợp với các nhà trang trí, một cơ chế đơn giản cho đa phương thức có thể được thực hiện.

# This is in the 'mm' module

registry = {}
import inspect

class MultiMethod(object):
    def __init__(self, name):
        self.name = name
        self.typemap = {}
    def __call__(self, *args):
        types = tuple(arg.__class__ for arg in args) # a generator expression!
        function = self.typemap.get(types)
        if function is None:
            raise TypeError("no match")
        return function(*args)
    def register(self, types, function):
        if types in self.typemap:
            raise TypeError("duplicate registration")
        self.typemap[types] = function

def multimethod(function):
    name = function.__name__
    mm = registry.get(name)
    if mm is None:
        mm = registry[name] = MultiMethod(name)
    spec = inspect.getfullargspec(function)
    types = tuple(spec.annotations[x] for x in spec.args)
    mm.register(types, function)
    return mm

và một ví dụ về việc sử dụng:

from mm import multimethod

@multimethod
def foo(a: int):
    return "an int"

@multimethod
def foo(a: int, b: str):
    return "an int and a string"

if __name__ == '__main__':
    print("foo(1,'a') = {}".format(foo(1,'a')))
    print("foo(7) = {}".format(foo(7)))

Điều này có thể được thực hiện bằng cách thêm các loại vào trình trang trí như bài đăng gốc của Guido , nhưng chú thích chính các tham số sẽ tốt hơn vì nó tránh được khả năng khớp sai các tham số và loại.

Lưu ý : Trong Python bạn có thể truy cập vào các chú thích như function.__annotations__chứ không phải function.func_annotationslà func_*phong cách đã được gỡ bỏ trên Python 3.

Uri đã đưa ra một câu trả lời thích hợp, vì vậy đây là một câu trả lời ít nghiêm trọng hơn: Vì vậy, bạn có thể làm cho các bài giảng của mình ngắn hơn.

Lần đầu tiên tôi nhìn thấy các chú thích, tôi đã nghĩ "tuyệt vời! Cuối cùng tôi có thể chọn tham gia một số loại kiểm tra!" Tất nhiên, tôi đã không nhận thấy rằng các chú thích không thực sự được thi hành.

Vì vậy, tôi quyết định viết một trình trang trí chức năng đơn giản để thực thi chúng :

def ensure_annotations(f):
    from functools import wraps
    from inspect import getcallargs
    @wraps(f)
    def wrapper(*args, **kwargs):
        for arg, val in getcallargs(f, *args, **kwargs).items():
            if arg in f.__annotations__:
                templ = f.__annotations__[arg]
                msg = "Argument {arg} to {f} does not match annotation type {t}"
                Check(val).is_a(templ).or_raise(EnsureError, msg.format(arg=arg, f=f, t=templ))
        return_val = f(*args, **kwargs)
        if 'return' in f.__annotations__:
            templ = f.__annotations__['return']
            msg = "Return value of {f} does not match annotation type {t}"
            Check(return_val).is_a(templ).or_raise(EnsureError, msg.format(f=f, t=templ))
        return return_val
    return wrapper

@ensure_annotations
def f(x: int, y: float) -> float:
    return x+y

print(f(1, y=2.2))

>>> 3.2

print(f(1, y=2))

>>> ensure.EnsureError: Argument y to <function f at 0x109b7c710> does not match annotation type <class 'float'>

Tôi đã thêm nó vào thư viện Đảm bảo .

Đã rất lâu kể từ khi điều này được hỏi nhưng đoạn trích ví dụ được đưa ra trong câu hỏi là (như đã nêu ở đó) từ PEP 3107 và ở cuối ví dụ PEP Các trường hợp sử dụng cũng được đưa ra có thể trả lời câu hỏi từ điểm PEP của lượt xem ;)

Sau đây được trích dẫn từ PEP3107

Trường hợp sử dụng

Trong quá trình thảo luận về các chú thích, một số trường hợp sử dụng đã được nêu ra. Một số trong số này được trình bày ở đây, được nhóm theo loại thông tin họ truyền tải. Cũng bao gồm các ví dụ về các sản phẩm và gói hiện có có thể sử dụng các chú thích.

• Cung cấp thông tin đánh máy
  • Kiểm tra loại ([3], [4])
  • Để IDE hiển thị loại chức năng mong đợi và trả về ([17])
  • Chức năng nạp chồng / hàm chung ([22])
  • Cầu nối ngoại ngữ ([18], [19])
  • Thích ứng ([21], [20])
  • Chức năng logic dự đoán
  • Ánh xạ truy vấn cơ sở dữ liệu
  • Sắp xếp tham số RPC ([23])
• Thông tin khác
  • Tài liệu cho các tham số và giá trị trả về ([24])

Xem PEP để biết thêm thông tin về các điểm cụ thể (cũng như các tài liệu tham khảo của họ)

Python 3.X (chỉ) cũng tổng quát hóa định nghĩa hàm để cho phép các đối số và trả về các giá trị được chú thích với các giá trị đối tượng để sử dụng trong các phần mở rộng .

Dữ liệu META của nó để giải thích, để rõ ràng hơn về các giá trị hàm.

Các chú thích được mã hóa như :valuesau tên đối số và trước mặc định và như ->valuesau danh sách đối số.

Chúng được thu thập vào một __annotations__thuộc tính của hàm, nhưng không được coi là đặc biệt bởi chính Python:

>>> def f(a:99, b:'spam'=None) -> float:
... print(a, b)
...
>>> f(88)
88 None
>>> f.__annotations__
{'a': 99, 'b': 'spam', 'return': <class 'float'>}

Nguồn: Tham khảo Pocket Python, Phiên bản thứ năm

THÍ DỤ:

Các typeannotationsmô-đun cung cấp một bộ công cụ để kiểm tra kiểu và suy luận kiểu mã Python. Nó cũng cung cấp một tập hợp các loại hữu ích để chú thích các hàm và đối tượng.

Các công cụ này được thiết kế chủ yếu để được sử dụng bởi các máy phân tích tĩnh như linters, thư viện hoàn thành mã và IDE. Ngoài ra, trang trí để thực hiện kiểm tra thời gian chạy được cung cấp. Kiểm tra loại thời gian chạy không phải lúc nào cũng là một ý tưởng tốt trong Python, nhưng trong một số trường hợp, nó có thể rất hữu ích.

https://github.com/ceronman/typeannotations

Cách gõ giúp viết mã tốt hơn

Nhập văn bản có thể giúp bạn thực hiện phân tích mã tĩnh để bắt lỗi loại trước khi bạn gửi mã của mình đến sản xuất và ngăn bạn khỏi một số lỗi rõ ràng. Có những công cụ như mypy, bạn có thể thêm vào hộp công cụ của mình như một phần của vòng đời phần mềm. mypy có thể kiểm tra các loại chính xác bằng cách chạy với codebase của bạn một phần hoặc toàn bộ. mypy cũng giúp bạn phát hiện các lỗi như kiểm tra loại Không khi giá trị được trả về từ một hàm. Gõ giúp làm cho mã của bạn sạch hơn. Thay vì ghi lại mã của bạn bằng cách sử dụng các nhận xét, trong đó bạn chỉ định các loại trong chuỗi doc, bạn có thể sử dụng các loại mà không phải trả bất kỳ chi phí hiệu năng nào.

Làm sạch Python: Mã hóa thanh lịch trong Python Mã số: ISBN-13 (pbk): 980-1-4842-4877-5

PEP 526 - Cú pháp cho chú thích biến

https://www.python.org/dev/peps/pep-0526/

https://www.attrs.org/en/urdy/types.html

Mặc dù tất cả các cách sử dụng được mô tả ở đây, việc sử dụng các chú thích có thể thi hành và rất có thể được thi hành sẽ dành cho các gợi ý kiểu .

Điều này hiện không được thi hành theo bất kỳ cách nào, nhưng, đánh giá từ PEP 484, các phiên bản tương lai của Python sẽ chỉ cho phép các loại làm giá trị cho các chú thích.

Trích dẫn Điều gì về việc sử dụng các chú thích hiện có? :

Chúng tôi hy vọng rằng các gợi ý loại cuối cùng sẽ trở thành việc sử dụng duy nhất cho các chú thích, nhưng điều này sẽ yêu cầu thảo luận bổ sung và thời gian khấu hao sau khi đưa ra mô-đun gõ đầu tiên với Python 3.5. PEP hiện tại sẽ có trạng thái tạm thời (xem PEP 411) cho đến khi Python 3.6 được phát hành. Lược đồ có thể hiểu nhanh nhất sẽ đưa ra sự phản đối thầm lặng của các chú thích không loại gợi ý trong 3.6, khấu hao hoàn toàn trong 3.7 và khai báo các gợi ý loại như là chỉ sử dụng các chú thích trong Python 3.8.

Mặc dù tôi chưa thấy bất kỳ sự phản đối thầm lặng nào trong 3.6, nhưng điều này rất có thể được đưa lên 3.7, thay vào đó.

Vì vậy, mặc dù có thể có một số trường hợp sử dụng tốt khác, tốt nhất là giữ chúng chỉ để gợi ý loại nếu bạn không muốn thay đổi mọi thứ trong tương lai khi có hạn chế này.

Như một câu trả lời chậm trễ, một số gói của tôi (marrow.script, WebCore, v.v.) sử dụng các chú thích có sẵn để khai báo typecasting (nghĩa là chuyển đổi các giá trị đến từ web, phát hiện đối số nào là công tắc boolean, v.v.) như để thực hiện đánh dấu bổ sung của các đối số.

Marrow Script xây dựng một giao diện dòng lệnh hoàn chỉnh cho các hàm và các lớp tùy ý và cho phép xác định các giá trị mặc định của tài liệu, truyền và gọi lại thông qua các chú thích, với một trình trang trí để hỗ trợ các thời gian chạy cũ hơn. Tất cả các thư viện của tôi sử dụng chú thích đều hỗ trợ các biểu mẫu:

any_string  # documentation
any_callable  # typecast / callback, not called if defaulting
(any_callable, any_string)  # combination
AnnotationClass()  # package-specific rich annotation object
[AnnotationClass(), AnnotationClass(), …]  # cooperative annotation

Hỗ trợ "Bare" cho các tài liệu hoặc chức năng typecasting cho phép trộn dễ dàng hơn với các thư viện khác có chú thích. (Tức là có một bộ điều khiển web sử dụng typecasting cũng được hiển thị dưới dạng tập lệnh dòng lệnh.)

Đã chỉnh sửa để thêm: Tôi cũng đã bắt đầu sử dụng gói TypeGuard bằng cách sử dụng các xác nhận trong thời gian phát triển để xác thực. Lợi ích: khi chạy với "tối ưu hóa" được bật ( -O/ PYTHONOPTIMIZEenv var), các kiểm tra, có thể tốn kém (ví dụ đệ quy) bị bỏ qua, với ý tưởng rằng bạn đã kiểm tra đúng ứng dụng của mình trong quá trình phát triển nên việc kiểm tra không cần thiết trong sản xuất.

Chú thích có thể được sử dụng để dễ dàng mô đun hóa mã. Ví dụ, một mô-đun cho một chương trình mà tôi đang duy trì có thể chỉ định nghĩa một phương thức như:

def run(param1: int):
    """
    Does things.

    :param param1: Needed for counting.
    """
    pass

và chúng ta có thể yêu cầu người dùng cho một thứ có tên "param1" là "Cần thiết để đếm" và phải là "int". Cuối cùng, chúng tôi thậm chí có thể chuyển đổi chuỗi do người dùng cung cấp sang loại mong muốn để có được trải nghiệm miễn phí rắc rối nhất.

Xem đối tượng siêu dữ liệu chức năng của chúng tôi để biết một lớp nguồn mở giúp với điều này và có thể tự động truy xuất các giá trị cần thiết và chuyển đổi chúng thành bất kỳ loại mong muốn nào (vì chú thích là một phương thức chuyển đổi). Ngay cả các IDE cũng hiển thị tự động hoàn thành đúng và cho rằng các loại theo chú thích - một sự phù hợp hoàn hảo.

Nếu bạn nhìn vào danh sách các lợi ích của Cython, một vấn đề chính là khả năng cho trình biên dịch biết loại đối tượng Python là gì.

Tôi có thể hình dung một tương lai nơi Cython (hoặc các công cụ tương tự biên dịch một số mã Python của bạn) sẽ sử dụng cú pháp chú thích để thực hiện phép thuật của chúng.