Writing Open Source Library
0 likes1,107 views
Документ представляет собой рекомендации по созданию качественных open source библиотек на Python с акцентом на документацию, тестирование и использование хороших имен для API. Автор подчеркивает важность организационной структуры и ясности кода, а также необходимость высококачественной документации и примеров использования. Также рассматриваются подходы к видимости классов и методов, использование наследования и агрегации, а также некоторые принципы работы с исключениями и логированием.
![Коллекции
class ReadonlyDict(collections.abc.Mapping):
def __init__(self, dct):
self._dct = dct
def __len__(self):
return len(self._dct)
def __iter__(self):
return iter(self._dct)
def __getitem__(self, key):
return self._dct[key]
assert set(ReadonlyDict({'a': 1, 'b': 2}).keys()) == set('a', 'b')](https://image.slidesharecdn.com/open2-140604121606-phpapp01/85/Writing-Open-Source-Library-24-320.jpg)
![Неудачный пример
sqlalchemy.engine.result.RowProxy
Это, хмм, abc.Sequence
len(result_proxy)
'column_name' in result_proxy
result_proxy[0]
result_proxy['column_name']
result_proxy[1: 5]
result_proxy1 < result_proxy2
iter(result_proxy)](https://image.slidesharecdn.com/open2-140604121606-phpapp01/85/Writing-Open-Source-Library-25-320.jpg)
![Исключения
def login(login, passwd):
res = db.execute(
"SELECT * FROM users "
"WHERE login = %s", login)
return res['passwd'] == passwd
def login(login, passwd):
try:
res = db.execute(
"SELECT * FROM users "
"WHERE login = %s", login)
if res['passwd'] != passwd:
raise CannotLogin()
except DatabaseNotFoundError as ex:
raise CannotLogin() from ex](https://image.slidesharecdn.com/open2-140604121606-phpapp01/85/Writing-Open-Source-Library-26-320.jpg)
Writing Open Source Library
- 2. О себе ● 15 лет использования Python ● Python Core Developer ● Соавтор нескольких библиотек (asyncio, aiohttp, aiozmq, aiopg) ● [email protected] ● http://asvetlov.blogspot.com
- 4. Код на github Этого явно недостаточно
- 5. Публичность ● Не знают — не используют. ● Статьи, блоги, stackoverflow и т.д. ● Не жалейте время на bug tracker
- 6. Документация ● Шанс составить первое впечатление ● Английский ● Docstrings и README.rst — недостаточно ● Нарративность ● Примеры ● readthedocs.org
- 7. Тесты ● Читаемые и хорошо организованные ● Полные ● coverage.py ● Как минимум 95% покрытие ● Continuous Integration (travis-ci.org)
- 8. Код ● pep8 — обязательно ● VCS (гитхаб прекрасен) ● Версии продукта ● Ветки, тэги, релизы ● Примеры использования
- 9. Инфраструктура ● setup.py ● PyPI ● readthedocs ● travis-ci ● инструкция по установке
- 10. Ясность Хорошая библиотека — простая библиотека
- 11. Pubic и Private API class A: def __init__(self, param): self.param = param def public(self): return self.private() def private(self): return self.param * 2 class A: def __init__(self, param): self._param = param def public(self): return self._private() def _private(self): return self._param * 2
- 12. Public API ● по умолчанию всё "закрыть". ● открывать только то что сознательно желаем сделать открытым ● Не нужно бояться "закрытых" классов
- 13. Docstrings class A: def __init__(self, param): self._param = param def public(self): return self._private() def _private(self): """Private function""" return self._param * 2 class A: """Docstring for class""" def __init__(self, param): self._param = param def public(self): """This is public""" return self._private() def _private(self): # Private function return self._param * 2
- 14. Понятное API Если нелегко написать документацию — API плохое
- 15. Хорошие имена twisted.internet.defer. Deferred Twised's Deferred does something — OMG! asyncio.Future
- 16. Трудность выбора имен ZeroMQ Req/Rep, Push/Pull и Pub/Sub Requester? Pusher??? RPC Извещения Подписка Клиент Req Push Pub Сервер Rep Pull Sub
- 17. Решение connect_rpc — RPCClient serve_rpc — RPCServer connect_pipeline — PipelineClient serve_pipeline — PipelineServer connect_pubsub — PubSubClient serve_pubsub — PubSubServer
- 18. Наследование class Base: def do_work(self): self.handle('param') class Derived(Base): def handle(self, param): do_something() class Base(metaclass=abc.ABCMeta): def do_work(self): self.handle('param') @abc.abstractmethod def handle(self, param): pass class Derived(Base): def handle(self, param): do_something()
- 19. Агрегация лучше наследования class Service: def do_work(self): self.log('operaion') def log(self, param): pass class SocketLoggerMixin: def log(self, param): self.socket.send(param) class SocketLoggingService( SocketLoggerMixin, Service): pass class Service: def __init__(self, logger): self._logger = logger def do_work(self): self._logger.log('operaion') class Logger: def log(self, param): pass
- 20. Естественная полнота API class Subscriber: def subscribe(self, name): pass class Subscriber: def subscribe(self, name): pass def unsubscribe(self, name): pass @property def subscriptions(sef): pass
- 21. Предметная область Матрицы a * b a @ b a + b len(a)
- 22. Устоявшиеся соглашения class Point: def __init__(self, a, b): self.a, self.b = a, b def __add__(self, other): self.a += other.a self.b += other.b return self class Point: def __init__(self, x, y): self._x, self._y = x, y x = property(lambda self: self._x) y = property(lambda self: self._y) def __add__(self, other): return Point(self._x + other. _x, self._y + other. _y)
- 23. Магические методы def __eq__(self, other): if isinstance(other, Point): return self._x == other._x and self._y == other._y else: return NotImplented def __ne__(self, other): return not self == other def __hash__(self): return (self._x, self._y)
- 24. Коллекции class ReadonlyDict(collections.abc.Mapping): def __init__(self, dct): self._dct = dct def __len__(self): return len(self._dct) def __iter__(self): return iter(self._dct) def __getitem__(self, key): return self._dct[key] assert set(ReadonlyDict({'a': 1, 'b': 2}).keys()) == set('a', 'b')
- 25. Неудачный пример sqlalchemy.engine.result.RowProxy Это, хмм, abc.Sequence len(result_proxy) 'column_name' in result_proxy result_proxy[0] result_proxy['column_name'] result_proxy[1: 5] result_proxy1 < result_proxy2 iter(result_proxy)
- 26. Исключения def login(login, passwd): res = db.execute( "SELECT * FROM users " "WHERE login = %s", login) return res['passwd'] == passwd def login(login, passwd): try: res = db.execute( "SELECT * FROM users " "WHERE login = %s", login) if res['passwd'] != passwd: raise CannotLogin() except DatabaseNotFoundError as ex: raise CannotLogin() from ex
- 27. Singletons Просто зло. Я их не использую.
- 28. Логирование logging.getLogger('').info('log message') Настраивание объема сообщений в лог production != dev environment библиотека != приложение пользователя
- 29. Проверка параметров def write(self, data): if not isinstance(data, (bytes, bytearray, memoryview)): raise TypeError('data argument must be byte-ish (%r)', type(data)) if server_side: if not sslcontext: raise ValueError('Server side ssl needs a valid SSLContext')
- 30. библиотека != приложение ● Обратная совместимость ● Внимание к деталям ● Простота и понятность ● Документация