Skip to content

QuecPython/quecpython_api_stubs

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

12 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

pyi文件介绍

本文件主要简单介绍pyi文件如何编写。详细介绍请参阅:https://peps.python.org/pep-0484/

什么是pyi文件? 在Python3中,.pyi文件是存根文件(stub file)。这个"pyi"中的"i"代表接口即interface,作为公共接口。 存根文件仅包含模块公共接口的描述,没有任何实现。

编写请参考模板:usocket.pyi

示例讲解

示例一

以下是pyi文件的函数定义

  • 1、如下参数后通过冒号标识该参数的类型(python基础类型:str、int、list、tuple...更多自定义类型参阅PEP484)。
  • 2、函数定义关键字def语句中,形参列表后,冒号前通过-> {类型}来标识当前函数的返回值类型。
  • 3、函数体首行注释(注:必须是三对双引号的注释且必须是函数体首行)
  • 4、文档建议采用reStructuredText风格。详细请参阅:https://wiki.python.org/moin/reStructuredText
def getaddrinfo(host: str, port: int = 8080):
    """Parses the domain name of DNS. —— (此处是当前函数的简略注释信息。)

    Parses the domain name of the host (host) and port (port) into a 5-tuple sequence used to create the socket. The structure of the tuple is below:
    (family, type, proto, canonname, sockaddr) —— (此处是当前函数的详细注释信息。)
    
    @param host: The domain name of the host.
    @param port: The port.
    @return: (family, type, proto, canonname, sockaddr)
    """
    ...  # 注:pyi文件中允许使用"..."代替任何实现细节。它是仅包含类型信息的文件,没有运行时代码。另,此处函数体可以留空,`...`是非必要的。

示例二

该示例表示一个只有单行文档注释的函数定义。

def allocate_lock():
    """Creates and Return a mutex object."""

示例三

AF_INET = ...  # 地址族,IPV4类型。
AF_INET6 = ...  # 地址族,IPV6类型。
SOCK_STREAM = ...  # socket类型,TCP的流式套接字。
IPPROTO_TCP = ...  # 协议号,TCP协议。
IPPROTO_UDP = ...  # 协议号,UDP协议。


class socket(object):
    """Socket"""

    def __init__(self, af=AF_INET, type=SOCK_STREAM, proto=IPPROTO_TCP):
        """Socket对象初始化函数。
    	
    	NOTE:
        根据给定的地址族、套接字类型以及协议类型参数,创建一个新的套接字对象。
        在大多数情况下不需要指定proto,也不建议这样做,因为某些MicroPython端口可能会省略IPPROTO_*常量。
    
        @af:地址族(参考常量说明)。
        @type:socket类型(参考常量说明)。
        @proto:协议号(参考常量说明)。
        """
    
    def bind(self, address: tuple = ("192.168.0.1", 80)):
        """该方法用于套接字绑定指定address,必须尚未绑定。
    	
    	NOTE:
        1、作为服务器时,需要进行绑定,以固定服务器的address。
        2、作为客户端时,绑定address用来指定套接字进行数据处理(配合usocket.TCP_CUSTOMIZE_PORT使用)。
    
        @address:包含地址和端口号的元组或列表。
        """
    
    def listen(self, backlog: int):
        """该方法用于套接字服务端开启监听客户端连接,可指定最大客户端连接数。
    
        @backlog:接受套接字的最大个数,至少为0。
        """
    
    def accept(self):
        """该方法用于套接字服务端接受连接请求。
    
        @return:成功返回元组,包含新的套接字和客户端地址以及客户端端口,形式为:(conn,address,port)。
        conn,新的套接字对象,用来和客户端交互;
        address,连接到服务器的客户端地址;
        port,连接到服务器的客户端端口。
        """

About

No description or website provided.

Topics

Resources

Stars

Watchers

Forks

Packages

No packages published

Contributors 3

  •  
  •  
  •  

Languages