pygolang 0.1

GPython

命令 gpython 提供了一个支持通过紧集成 gevent 实现轻量级线程的Python解释器。GPython的标准库与Python标准库的API兼容，但提供轻量级协程代替OS线程，并通过基于 libuv/libev 的IO调度器内部组织IO。因此，程序可以以低廉的成本创建大量的协程，并且像 time、socket、ssl、subprocess 等模块都可以被所有协程同时使用，就像每个协程都是一个完整的OS线程一样。这为在不更改并发模型和现有代码的情况下扩展程序提供了能力。

此外，GPython始终将UTF-8设置为默认编码，并将 go、chan、select 等放入内置命名空间。

协程和通道

go生成一个协程，如果没有激活gevent，则生成线程。可以通过通道在线程或协程之间交换数据。使用 chan.recv、chan.send 和 chan.close 进行通信。nilchan 代表空通道。select 可用于在多个通道上进行多路复用。例如：

ch1 = chan()    # synchronous channel
ch2 = chan(3)   # channel with buffer of size 3

def _():
    ch1.send('a')
    ch2.send('b')
go(_)

ch1.recv()      # will give 'a'
ch2.recv_()     # will give ('b', True)

ch2 = nilchan   # rebind ch2 to nil channel
_, _rx = select(
    ch1.recv,           # 0
    ch1.recv_,          # 1
    (ch1.send, obj),    # 2
    ch2.recv,           # 3
    default,            # 4
)
if _ == 0:
    # _rx is what was received from ch1
    ...
if _ == 1:
    # _rx is (rx, ok) of what was received from ch1
    ...
if _ == 2:
    # we know obj was sent to ch1
    ...
if _ == 3:
    # this case will be never selected because
    # send/recv on nil channel block forever.
    ...
if _ == 4:
    # default case
    ...

默认情况下，chan 创建可以携带任意Python对象的通道。但是，可以通过 chan(dtype=X) 指定通道元素的类型 - 例如，chan(dtype='C.int') 创建一个元素为C整数的通道。chan.nil(X) 创建一个有类型的空通道。Cython/nogil API 解释了如何使用非Python dtypes的通道，除了在Python中使用外，还可以用于Python和nogil世界之间的交互。

方法

func 装饰器允许独立于类定义方法。

例如

@func(MyClass)
def my_method(self, ...):
    ...

将定义 MyClass.my_method()。

func 还可以用于仅函数，例如

@func
def my_function(...):
    ...

Defer / recover / panic

defer 允许在当前函数返回时调度清理操作。它与 try/finally 类似，但不会强制将清理部分放在最后。例如

wc = wcfs.join(zurl)    │     wc = wcfs.join(zurl)
defer(wc.close)         │     try:
                        │        ...
...                     │        ...
...                     │        ...
...                     │     finally:
                        │        wc.close()

如果延迟清理失败，则先前未处理的异常（如果有的话）不会丢失 - 它将使用 (PEP 3134) 连接并包含到traceback输出中，即使在Python2上也是如此。

为了完整性，还有 recover 和 panic，允许以Go风格的错误处理编程，例如

def _():
   r = recover()
   if r is not None:
      print("recovered. error was: %s" % (r,))
defer(_)

...

panic("aaa")

但是，recover 和 panic 可能不太有用，因为它们可以用 try/except 本地建模。

如果使用 defer，则使用它的函数必须用 @func 装饰器包装。

错误

在并发系统中，操作堆栈通常与执行代码流程不同，这使得代码堆栈跟踪对理解错误来说非常有用。Pygolang提供了错误链支持，可以构建操作错误堆栈并检查结果错误。

error 是一种可以单独使用或被继承的错误类型。通过提供 .Unwrap() 方法，错误可以可选地包装另一个错误，从而形成一个错误链。使用 errors.Is 可以判断错误链中的某个项是否匹配目标。使用 fmt.Errorf 提供了一种方便的方式来构建包装错误。例如

e1 = error("problem")
e2 = fmt.Errorf("doing something for %s: %w", "joe", e1)
print(e2)         # prints "doing something for joe: problem"
errors.Is(e2, e1) # gives True

# OpError is example class to represents an error of operation op(path).
class OpError(error):
   def __init__(e, op, path, err):
      e.op   = op
      e.path = path
      e.err  = err

   # .Error() should be used to define what error's string is.
   # it is automatically used by error to also provide both .__str__ and .__repr__.
   def Error(e):
      return "%s %s: %s" % (e.op, e.path, e.err)

   # provided .Unwrap() indicates that this error is chained.
   def Unwrap(e):
      return e.err

mye = OpError("read", "file.txt", io.ErrUnexpectedEOF)
print(mye)                          # prints "read file.txt: unexpected EOF"
errors.Is(mye, io.EOF)              # gives False
errors.Is(mye. io.ErrUnexpectedEOF) # gives True

被包装的和包装的错误可以是任意 Python 类型，不一定是 error 或其子类。

error 还用于表示在 Python 级别由 Cython/nogil 调用返回的错误（见 Cython/nogil API）并保留 Cython/nogil 错误链以在 Python 级别进行检查。

Pygolang 错误链与 Python 错误链集成，并考虑了通过 raise X from Y（PEP 3134）创建的异常的 .__cause__ 属性。

字符串

b 和 u 提供了一种确保对象是字节或 unicode 的方法。使用 b(obj) 将 str/unicode/bytes 对象转换为 UTF-8 编码的字节串，而使用 u(obj) 将 str/unicode/bytes 对象转换为 unicode 字符串。例如

b("привет мир")   # -> gives bytes corresponding to UTF-8 encoding of "привет мир".

def f(s):
   s = u(s)       # make sure s is unicode, decoding as UTF-8(*) if it was bytes.
   ...            # (*) but see below about lack of decode errors.

编码和解码的转换永远不会失败，也不会丢失信息：b(u(·)) 和 u(b(·)) 总是对应于字节和 unicode 的恒等，即使字节输入不是有效的 UTF-8。

导入

gimport 提供了一种在 Go 工作空间中通过完整路径导入 Python 模块的方法。

例如

lonet = gimport('lab.nexedi.com/kirr/go123/xnet/lonet')

将导入以下之一

• lab.nexedi.com/kirr/go123/xnet/lonet.py，或

• lab.nexedi.com/kirr/go123/xnet/lonet/__init__.py

位于 src/ 下 $GOPATH 的位置。

Cython/nogil API

Cython 包 golang 提供了具有 goroutines、channels 等功能，与相应的 Python 包相对应的 nogil API。与 Python 版本相比，Cython API 不仅更快，而且由于 nogil 特性，允许在 Python 类似的语言中进行编程的同时构建无限制的并发系统。以下是对 Cython/nogil API 的简要描述

go 会启动一个新的任务 - 一个协程或线程，具体取决于激活的运行时。表示具有 Go 语义和类型 T 的元素的 chan[T]。使用 makechan[T] 创建新通道，并使用 chan[T].recv、chan[T].send、chan[T].close 进行通信。表示空通道的 nil。可以使用 select 在多个通道上进行多路复用。例如

cdef nogil:
   struct Point:
      int x
      int y

   void worker(chan[int] chi, chan[Point] chp):
      chi.send(1)

      cdef Point p
      p.x = 3
      p.y = 4
      chp.send(p)

   void myfunc():
      cdef chan[int]   chi = makechan[int]()       # synchronous channel of integers
      cdef chan[Point] chp = makechan[Point](3)    # channel with buffer of size 3 and Point elements

      go(worker, chi, chp)

      i = chi.recv()    # will give 1
      p = chp.recv()    # will give Point(3,4)

      chp = nil         # rebind chp to nil channel
      cdef cbool ok
      cdef int j = 33
      _ = select([
          chi.recvs(&i),         # 0
          chi.recvs(&i, &ok),    # 1
          chi.sends(&j),         # 2
          chp.recvs(&p),         # 3
          default,               # 4
      ])
      if _ == 0:
          # i is what was received from chi
          ...
      if _ == 1:
          # (i, ok) is what was received from chi
          ...
      if _ == 2:
          # we know j was sent to chi
          ...
      if _ == 3:
          # this case will be never selected because
          # send/recv on nil channel block forever.
          ...
      if _ == 4:
          # default case
          ...

Python 通道由表示为 pychan cdef 类的 pychan 表示。携带非 Python 元素（pychan.dtype != DTYPE_PYOBJECT）的 Python 通道可以通过 pychan.chan_*() 转换为 Cython/nogil chan[T]。同样，Cython/nogil chan[T] 可以通过 pychan.from_chan_*() 包装到 pychan 中。这提供了在 nogil 和 Python 世界之间交互的机制。例如

def myfunc(pychan pych):
   if pych.dtype != DTYPE_INT:
      raise TypeError("expected chan[int]")

   cdef chan[int] ch = pych.chan_int()  # pychan -> chan[int]
   with nogil:
      # use ch in nogil code. Both Python and nogil parts can
      # send/receive on the channel simultaneously.
      ...

def mytick(): # -> pychan
   cdef chan[int] ch
   with nogil:
      # create a channel that is connected to some nogil task of the program
      ch = ...

   # wrap the channel into pychan. Both Python and nogil parts can
   # send/receive on the channel simultaneously.
   cdef pychan pych = pychan.from_chan_int(ch)  # pychan <- chan[int]
   return pych

error 是表示错误的接口。使用 errors.New 和 fmt.errorf 可以从文本构建错误。错误可以通过实现 errorWrapper 接口并提供 .Unwrap() 方法来可选地包装另一个错误。使用 errors.Is 可以判断错误链中的某个项是否匹配目标。使用 fmt.errorf 与 %w 说明符提供了一种方便的方式来构建包装错误。例如

e1 = errors.New("problem")
e2 = fmt.errorf("doing something for %s: %w", "joe", e1)
e2.Error()        # gives "doing something for joe: problem"
errors.Is(e2, e1) # gives True

可以通过 pyerror cdef 类包装器实例化 pyerror.from_error() 将 error 暴露给 Python。通过 Python 级别的 error.Is，pyerror 保留了 Cython/nogil 错误链以进行检查。

panic 通过抛出 C 级别异常来停止当前 goroutine 的正常执行。在 Python/C 边界，必须使用 topyexc 将 C 级别异常转换为 Python 级别异常。例如

cdef void _do_something() nogil:
   ...
   panic("bug")   # hit a bug

# do_something is called by Python code - it is thus on Python/C boundary
cdef void do_something() nogil except +topyexc:
   _do_something()

def pydo_something():
   with nogil:
      do_something()

请参阅 libgolang.h 和 golang.pxd 以了解 API 的详细信息。还可以参阅 testprog/golang_pyx_user/ 以了解使用 Pygolang 的 Cython/nogil 模式的示例项目。

额外的包和工具

还提供以下额外的包和工具来弥合 Python/Cython 和 Go 环境之间的差距

print('hello %s' % qq(name))

def bench_add(b):
    x, y = 1, 2
    for i in xrange(b.N):
        x + y

$ py.bench --count=3 x.py
...
pymod: bench_add.py
Benchmarkadd    50000000        0.020 µs/op
Benchmarkadd    50000000        0.020 µs/op
Benchmarkadd    50000000        0.020 µs/op

GPython选项

GPython 仿真并支持大多数 Python 命令行选项，例如 gpython -c <commands> 从命令行运行 Python 语句，或 gpython -m <module> 执行模块。这些选项的含义与标准 Python 相同，此处未进行说明。

以下列出了 GPython 特定的选项和环境变量

-X gpython.runtime=(gevent|threads)

指定 GPython 应使用哪个运行时。 gevent 提供轻量级协程，而使用 threads 时，go 会生成完整的 OS 线程。gevent 是默认设置。也可以通过 $GPYTHON_RUNTIME 环境变量指定要使用的运行时。

Pygolang变更历史