smokesignal 0.7.0

# smokesignal - 简单的Python信号

[](https://travis-ci.org/shaunduncan/smokesignal)

`smokesignal`是一个用于发送和接收信号的简单的Python库。
它从django信号框架中汲取了一些灵感，但旨在作为
通用变体。


## 要求与兼容性

`smokesignal`不需要除Python标准库之外的其他依赖项。
它已在Python 2.6、2.7、3.2和3.3版本上进行了测试，并且与之兼容。


## 使用方法

`smokesignal`的大部分使用涉及使用`on`注册单个可调用对象以响应信号
使用`emit`发送信号。

### 注册回调

大多数回调注册都是使用`on`完成的，它可以作为装饰器
或直接函数调用使用。此方法还接受一个可选参数`max_calls`，该参数
表示回调应该响应发射信号的次数的最大值

```python
import smokesignal

@smokesignal.on('foo')
def my_callback()
pass

@smokesignal.on('foo', max_calls=2)
def my_callback()
pass

smokesignal.on('foo', my_callback, max_calls=5)
```

如果您希望回调函数最多只响应一次信号，而不是使用
`max_calls=1`来指示，可以使用`once`作为便捷方式

```python
import smokesignal

@smokesignal.once('foo')
def my_callback()
pass
```

### 发送信号

信号通过使用`emit`方法发送到所有已注册的回调。此方法可选地接受
参数和关键字参数列表，这些参数将被直接传递给每个回调

```python
import smokesignal

# 调用响应'foo'的每个回调
smokesignal.emit('foo')

# 调用响应'foo'的每个回调，并传递参数
smokesignal.emit('foo', 1, 2, 3, four=4)
```

您还可以使用包含的上下文管理器`emitting`来发送信号。默认情况下，此
上下文管理器接受一个参数，即上下文管理器退出时要发送的信号。但是，
您可以为`enter`和`exit`提供关键字参数，这些参数将在上下文管理器的
这些点上发送

```python
import smokesignal

# 在退出时发射'foo'
with smokesignal.emitting('foo')
pass

# 在进入时发射'foo'，在退出时发射'bar'
with smokesignal.emitting(enter='foo', exit='bar')
pass
```

### 断开回调连接

如果您不再希望回调函数响应任何信号，可以使用`disconnect_from`
来移除特定信号，或者使用`disconnect`来移除所有信号


```python
import smokesignal

# my_callback将不再响应信号
smokesignal.disconnect(my_callback)

# my_callback将不再响应'foo'，但可能响应其他信号
smokesignal.disconnect_from(my_callback, 'foo')
```

### 其他功能


您可以使用`clear`或`clear_all`清除大量的回调
如果没有参数调用`clear`，它实际上类似于`clear_all`

```python
# 移除响应特定信号的回调
smokesignal.clear('foo')

# 移除响应所有信号的回调
smokesignal.clear_all()
smokesignal.clear()
```

有时您可能想要获取一个回调函数响应的信号列表，或者快速检查
回调函数是否响应某个特定的信号。`signals`和`responds_to`
可用于此目的。请注意，将回调函数注册为响应信号将同时创建回调函数
的调用属性，以便更容易与这些方法交互


```python
# 获取回调函数响应的所有信号元组
smokesignal.signals(my_callback)

# 检查回调函数是否响应信号
smokesignal.responds_to(my_callback, 'foo')

# 或作为回调函数的属性
my_callback.signals()
my_callback.responds_to('foo')
```


## 注意事项

如果能使用`on`或`once`装饰实例方法将是非常好的。但是，这不可行，因为
在回调函数注册以响应信号时，没有关于类实例的知识


```python
import smokesignal

class Foo(object)

# 这不可行
@smokesignal.on('bar')
def callback(self)
pass
```



```python
import smokesignal

class Foo(object)
def __init__(self, *args, **kwargs)
smokesignal.on('bar', self.callback)
super(Foo, self).__init__(*args, **kwargs)

def callback(self)
pass
```

上述方法将注册回调而无需任何参数要求，但也将确保正确调用
“预期”的回调方法。


## 更新日志

### 0.3
- 回调函数现在具有可调用的属性`responds_to`和`signals`
- 调用`clear`而不带任何参数将清除所有信号的回调

### 0.2
- 添加了`emitting`上下文管理器
- 更新内部不再需要装饰器魔法来强制执行最大调用次数

### 0.1
- 初始版本


## 贡献和许可

由[Shaun Duncan](mailto:shaun.duncan@gmail.com)开发，是
根据MIT许可证的条款授权。