web2py

Chapter 15: Оказание помощи web2py

Оказание помощи web2py: ошибки, улучшения и документация

web2py приветствует сообщения об ошибках, документации и усовершенствований.

Группа Google

Главным форумом для обсуждения ошибок и новых функций является: web2py-users (URL is https://groups.google.com/forum/#!forum/web2py)

Подача отчета об ошибке

До января 2015 года выпуски не отслеживались на Google Code, и многие исторические ссылки в группе новостей и в старых документах направят вас туда. В рамках перехода на GitHub, проект теперь использует выпуски GitHub. Только открытые выпуски были переданы в GitHub.

Если вы нашли ошибку и обсуждали это в группе, то вы можете предложить подать отчет об ошибке путем создания Issue на GitHub.

Пожалуйста, посетите страницу GitHub проекта и перейдите по ссылке на Issues.

https://github.com/web2py/web2py

(или непосредственно посетите https://github.com/web2py/web2py/issues) .

Как обычно, хорошая отчетность об ошибке означает то, что мы должны знать вашу операционную систему, версию Python и web2py, что должно было произойти, и что получилось вместо этого. Бонусные баллы при размещении полного примера кода, который указывает на вопрос: немного кода лучше, чем тысяча слов.

Отчеты об ошибках безопасности

reporting security bugs

При составлении отчетов об ошибках безопасности, будьте осторожны при раскрытии информации, которая может способствовать злонамеренный эксплуатации. После размещения в группе Google или поднимая проблему в GitHub, вам необходимо связаться с разработчиком для обмена информацией в частном порядке.

Содействие при написании кода и документировании изменений

Как управляется код проекта

Базовый код Web2py управляется в git-репозитории GitHub. Оригинальная система управления версиями Mercurial ранее находилась на Google Code, но сейчас идет активная разработка на GitHub.

PyDAL: DAL в настоящее время является независимым проектом

Важной частью web2py является Абстрактный Уровень Базы данных (DAL). В начале 2015 года данный модуль был отделен в отдельный код базы (PyDAL). С точки зрения Git, это суб-модуль основного репозитория.

Использование суб-модуля требует одноразового использования флага --recursive для git клона, если вы клонировали web2py с нуля.


git clone --recursive https://github.com/web2py/web2py.git

Если у вас есть существующий репозиторий, то команды ниже должны быть выполнены, по крайней мере один раз:

git submodule update --init --recursive

Если у вас есть папка gluon/dal, то вы должны удалить ее:

rm -r gluon/dal

PyDAL использует отдельный цикл стабильного выпуска к остальной части web2py. Выпуски PyDAL будут использовать схему наименований по дате, подобную Ubuntu. Вопросы, связанные с PyDAL должны быть представлены в своем отдельном репозитории.

GitHub репозитории

Репозитории GitHub:

https://github.com/web2py/web2py

https://github.com/web2py/pydal

web2py имеет две важные версии: текущая стабильная версия и снимок разработки. В git снимок разработки обычно называют как "master", но в проекте web2py обычно говорят "Ствол" ("trunk"), который является эквивалентным термином от Mercurial и SVN. Обратите внимание, что термин "ствол" прекрасно подходит для использования на производстве, но это не является гарантией. Пожалуйста, используйте маркированные релизы, если вам нужна стабильная база кода.

Исправления ошибок и улучшения идут в ствол, поэтому вам нужно будет использовать ствол для быстрого исправления ошибки. Лучший способ это клонировать репозиторий git. Это первый шаг при использовании кода, хранящегося и хорошо задокументированного на GitHub. Поскольку релизы помечаются, вы можете переключаться между ответвлением ствола (который 'master') и текущим релизом (или любым другим релизом). Это делает использование git-репозитория очень практичным, даже в производстве.

Вам понадобятся следующие навыки работы с git:

клонирование репозитория, размещенного на GitHub
извлечение наружу ветки(branch) мастера
проверка внешней ветки, основанной на метке

Они хорошо охватываются в руководстве по GitHub: смотрите ниже.

Обсуждение предлагаемых изменений

Если изменение относится к ошибке, то обсуждение по этому вопросу вероятнее всего будет происходить на GitHub (см выше). Если изменение относится к усовершенствованию, то изначально лучшим местом для обсуждения является группа разработчиков: группа разработчиков web2py (URL-Адрес https://groups.google.com/forum/#!forum/web2py-developers)

Поскольку web2py обещает обратную совместимость для неэкспериментальных функций, то принятие изменения в код базы является обещанием обслуживать будущих пользователей, и это не то обещание, которое может быть легко выполнено. Менее опытные пользователи в процессе обсуждения могут обнаружить, что существуют методы добиться того, чего они хотят; к сожалению, документирование сильных возможностей иногда отстает (см улучшение документации ниже).

Когда вы будете готовы подать изменение кода, то обсуждение изменений вероятнее всего перейдет в комментарии, прикрепленные к Pull Request (обсуждается ниже).

Стиль написания кода

coding style

Как правило, следует придерживаться стилю написания кода PEP8. http://www.python.org/dev/peps/pep-0008/

Существуют конкретные указания здесь: Стиль web2py

Стиль документации

стиль документации указывается ниже

Советы по настройке среды разработки

Глава 13 содержит некоторые советы по использованию различных интегрированных сред разработки (IDE) с web2py.

Приготовление: использование GitHub

patches

GitHub

Так как web2py использует GitHub, то общий поток изменений выглядит следующим образом:

Вы создаете клон web2py на GitHub, который GitHub называет "ответвление" ("forking").
Вы создаете клон своего web2py 'ответвления' ('fork') на локальной машине (или где вы хотите делать изменения)
Вы создаете новую ветвь (branch) для ваших изменений
Вы работаете над своей новой веткой и фиксируетесь
Вы выталкиваете (push) ваши изменения обратно на GitHub ответвление (fork) (git выталкивает (push) оригинальное имя новой ветви name_of_new_branch)
Вы делаете запрос на вытягивание (pull request) через GitHub
Если ваш запрос на вытягивание (pull request) будет принят, то ваша фиксация будет в главной (master) ветви web2py.

На момент написания, основные технические приемы git/GitHub охватываются здесь: https://help.GitHub.com/articles/fork-a-repo

Тем не менее, вам необходимо следовать нижеприведенным инструкциям по созданию патчей, которые в дальнейшем могут быть аккуратно объединены.

Обратите внимание: git-репозиторий web2py содержится в качестве подмодуля для DAL. Это означает, что при первоначальном извлечении следует использовать --recursive для инициализации подмодуля.

Приготовление: использование Travis с вашим GitHub ответвлением

travis

web2py работает с travis, непрерывным сервисом встроенного тестирования. Это означает, что фиксация будет вызывать все встроенные тесты модуля.

Вы можете легко добавить Travis в свой собственный репозиторий GitHub, чтобы избежать отправки исправлений, которые могут вывести из строя Travis тестирование вверх по течению.

Следуйте инструкциям здесь: http://about.travis-ci.org/docs/user/getting-started/

Четыре части хорошего качественного усовершенствования

Высококачественное усовершенствование имеет четыре части:

Изменение кода
Документирование изменений API (см API документацию ниже)
Тестирование новых функциональных возможностей
Обновление книги (которая также поддерживается на уровне GitHub)

Обеспечение чистоты патча: использование корректной GIT технологии ветвления (git branch)

git

Использование Git должным образом является немного более сложным в общем проекте.

Ниже приведены конкретные рекомендации, чтобы убедиться в чистоте применения вашего запроса на вытягивание (pull).

Во-первых, убедитесь, что у вас есть настройка удаленного хранилища, которая указывает на основной web2py GitHub репозиторий. Ваш удаленный репозиторий должен называться вверх по течению (upstream). Вы должны сделать это только один раз.

Добавление выше по потоку (upstream) репозитория покрывает вступительную указанную выше GitHub статью, но в случае, если вы пропустили его, то вы можете добавить вверх по течению (upstream) вроде этого:

git remote add upstream https://github.com/web2py/web2py/

Далее вам необходимо создать имя ветви (branch) для ваших изменений. Git поощряет много названий ветвлений, как можно более конкретным. Для web2py, мы рекомендуем имена вроде этих:

Каждое фиксируемая ошибка должна исходить от ветви с именем "issue/number_of_the_issue_on_github" (вроде issue/1684)
каждая фиксация улучшения должна приходить в ветку (branch) под названием "enhancement/title_of_the_enhancement" (вроде enhancement/trapped_links)

Трюк, чтобы обеспечить отправку чистого запроса на вытягивание, заключается в том, чтобы начало вашего ветвления (branch) всегда происходило из самого последнего кода web2py, который находится на мастер ветке (master branch).

Если вы никогда не работали на вашем репо-мастер ветви, то вы можете сохранить его в синхронизации с мастером web2py, и будете уверены что "играете безопасно" только в ваших вновь созданных ветвях.

Вы можете держать в синхронизации своего мастера с web2py с этими командами:

git checkout master
git fetch upstream
git merge upstream/master

Теперь ветви, в вашей локальной среде, контролируется на наличие ваших изменений (в то время как вы на мастере) ... подставьте CHANGE1 для вашего имени ветви.

git checkout -b CHANGE1

... Внесите изменения или вишневый выбрать из другой локальной ветви. Фиксируйтесь (commit) в случае необходимости. Когда вы будете готовы отправить ваши локальные изменения в ваше web2py ответвление(fork):

git push origin CHANGE1

Теперь ваша ветвь находится на GitHub ... перейти на веб-сайт GitHub, перейти к новой ветки и сделайте запрос на вытягивание.

GitHub имеет кнопку "удалить ветвь" после того, как ваш запрос на вытягивание (pull request) объединен или закрыт. Здесь не может быть никаких гарантий, но запросы на вытягивание, как правило, рассматривается в течение нескольких дней. Большинство людей, представляя патчи как запросы на вытягивание, также обновляют либо отчет о проблемах или усовершенствуют поток. Итак, помните, что если вы хотите начать новый запрос на вытягивание (pull request), то вы должны вернуться к мастер ветви на вашем репозитории, повторно синхронизироваться и создать новую ветку. Давайте предположим, что вам нужно создать другую ветвь с названием CHANGE2

git checkout master
git fetch upstream
git merge upstream/master
# now master is in sync
git checkout -b CHANGE2
...

Когда вы делаете несколько фиксаций (commit) на одной "особенной" ветке, то полученный результат слияния с запросом на вытягивание будет включать в себя каждую фиксацию, которую вы сделали на этой ветке. В целях поддержания "объединенного дерева" в чистоте, вы должны перебазировать ваш запрос на вытягивание только одну фиксацию в целях поддерживания содержания - в идеале -. В этом случае процесс перебазирования "переписывает" историю, удерживающую те же самые изменения в коде и в тоже время "сворачивает" все эти изменения в одну фиксацию.

Для того, чтобы начать процесс перебазирования, при нахождении в вашей ветви, сделайте что-то вроде:

git rebase --interactive HEAD~10

Этот код забирает до 10 последних фиксаций: то, что вам нужно сделать, так это изменить "выбранное" ("pick") в "патиссон" ("squash") в каждой фиксации, вам необходимо "свернуть", и оставить только один из них.

Добавление тестов

code tests

unit tests

Модульные тесты должны быть добавлены тогда, когда усовершенствования изменяют и добавляет функциональность. Тесты являются Python скриптами, которые содержатся в gluon/tests. Скопируйте подходящий из существующих тестов. Вам необходимо обратить внимание, что тестам часто необходимо создать нечто, например таблицы, выполнить тест функциональности и проверить итоги, а затем вернуться в состояние перед тестированием (что в данном случае будет означать удаление таблицы). Существует хорошая ссылка на тестирование здесь: Web2pyslice 1691

http://www.web2pyslices.com/slice/show/1691/help-developers-adding-tests-to-web2py

Выполнение тестов

Вы можете запустить все тесты:

python web2py.py --run_system_tests

Посмотрите ссылки выше для получения дополнительной информации, включая запуск отдельных тестов.

Пример единичного теста

Написать тест легко. Это пример из gluon/tests/test_dal.py Вы можете увидеть, как тест расширяет класс TestCase. Обратите внимание, как добавляется достаточно сложная таблица, как выполняется тест и проверяется выход, а затем изменения в базе данных откатываются назад, оставляя место разбивки теста в чистоте, как это было до вашего прибытия.

class TestVirtualFields(unittest.TestCase):

    def testRun(self):
        db = DAL(DEFAULT_URI, check_reserved=['all'])
        db.define_table('tt', Field('aa'))
        db.commit()
        db.tt.insert(aa="test")
        class Compute:
            def a_upper(row): return row.tt.aa.upper()
        db.tt.virtualfields.append(Compute())
        assert db(db.tt.id>0).select().first().a_upper == 'TEST'
        db.tt.drop()
        db.commit()

Документация: Обновление книги

Updating book

Книга также располагается на GitHub и используется тот же процесс работы с Git. Книга содержит источники на разных языках, которые находятся в каталоге sources. Содержимое написано на языке разметки markmin .

Подсказка: Содержание markmin книги использует якори для ссылок.

Для того, чтобы сослаться на якорь в другой главе книги, напишите ссылку вида:

[[markmin ../05#markmin_syntax]]

Книга представляет собой приложение web2py. Вы можете обнаружить, что удобнее всего сделать GitHub ответвление книги, и клонировать локальный репозиторий в каталог приложений из панели установки web2py. Это позволяет легко увидеть ваши изменения, которые отображаются в браузере.

Документация: web2pyslices.com

web2pyslices

web2pyslices.com

web2pyslices.com является ресурсом для рецептов, фрагментов кода и образцов.

Документация: API, документация в-коде (in-code) и docstring документация

Документация по API web2py здесь: http://web2py.readthedocs.org/en/latest/

Она использует Sphinx, который означает, что она формируется на основе документации, включенной в исходных файлах.

API (то есть docstrings) и in-code документация должна следовать Google Python Style Guide - Comments

Вот пример из web2py базы кода:

def getcfs(key, filename, filter=None):
    """
	Кэширует *отфильтрованный* файл `filename` с `key`, пока файл не будет изменен.

	Args:
	key(str): ключ кэша
	filename: файл для кэширования
	filter: является функцией, которая используется для фильтрации. Обычно `filename` является
	.py файлом и `filter` это функция, которая компилирует файл в байт-код .
	Таким образом, байт-код скомпилированный файл кэшируется. (Default = None)

	Это используется на Google App Engine, так как pyc файлы не могут быть сохранены.
	"""

и пример из руководства по стилю Google:

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
    """Выдает строки из Bigtable.

    Извлекает строки, относящиеся к заданным ключам от экземпляра Table,
    представленного big_table.  Глупые вещи могут случиться, 
    если other_silly_variable не равняется None.

    Args (Аргументы):
        big_table: Открытый Bigtable Table экземпляр.
        keys: Последовательность строк, представляющая ключ каждой строки таблицы
              для выборки.
        other_silly_variable: Другая необязательная переменная, 
		                      которая имеет гораздо более длинное название, 
							  чем другие args, и которая ничего не делает.

    Returns (Возврат):
        Словарь сопоставляет ключи с соответствующими
		извлеченными данными строк таблицы. Каждая строка
		является кортежем из строк. Например:

        {'Serak': ('Rigel VII', 'Preparer'),
         'Zim': ('Irk', 'Invader'),
         'Lrrr': ('Omicron Persei 8', 'Emperor')}

		Если ключ от аргумента ключей отсутствует в словаре,
		то эта строка не была найдена в таблице.

    Raises (подъемы):
        IOError: Произошла ошибка доступа к bigtable.Table объекту.
    """
    pass

Некоторые дополнительные web2py конкретные примечания повторяют API документацию через строки документации:

"Экспериментальные" функции должны быть четко обозначены
Sphinx был выбран потому, что он в значительной степени поддерживается, обслуживается и имеет дополнительный бонус readthedocs.org
новые функции должны быть четко обозначены (т.е. "начиная с 2.4.6...")
новые возможности должны быть тесно связаны с официальным журналом изменений
readthedocs.org позволяет строить "статически скомпонованную" версию Docs для будущих помеченных релизов (хорошо для "сравнение возможностей")
Разработчики web2py принимают руководство по стилю Google, так как оно предлагает лучшие Sphinx без всяких хлопотливых "украшений"
до выхода sphinx 1.3, sphinx-napoleon является требованием для построения документации

top

Полное справочное руководство, 6-е издание (предварительная версия). written by Massimo Di Pierro, перевод Игорь Москвитин in Русский

Search

Table of Contents