Достаточно ли контекста в вашем отчёте об ошибке?

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

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

Проблема одна и только одна?

Некоторые наши пользователи, похоже, считают, что есть предел проблем, которые они могут или должны открыть. На самом деле предела нет. Хотя может показаться привлекательным возможность свалить все свои проблемы в один билет, это означает, что тот, кто решает одну из ваших проблем, не может отметить проблему как закрытую. Как правило, сообщение о куче проблем приводит к тому, что билет остаётся открытым, поскольку никто не хочет браться за эту громадину, пока кто-нибудь милосердно не разделит проблему на несколько частей.

В частности, каждая проблема с поддержкой сайта должна относиться только к сервисам на одном сайте (обычно под общим доменом, но всегда с использованием одной и той же технологии бэкенда). Не запрашивайте поддержку для видео пользователей Vimeo, подкастов Whitehouse и страниц Google Plus в одном и том же вопросе. Также убедитесь, что вы не публикуете отчёты об ошибках вместе с запросами функций. Как правило, запрос функции не включает выходные данные youtube-dl, которые не связаны напрямую с рассматриваемой функцией. Не публикуйте отчёты о сетевой ошибке вместе с запросом на новую видеоуслугу.

Кому нужна эта функция?

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

Ваш вопрос о youtube-dl?

Может показаться странным, но некоторые отчёты об ошибках, которые мы получаем, совершенно не связаны с youtube-dl и относятся к другому приложению или даже к собственному приложению репортёра. Пожалуйста, убедитесь, что вы действительно используете youtube-dl. Если вы используете пользовательский интерфейс для youtube-dl, сообщите об ошибке сопровождающему фактического приложения, предоставляющего пользовательский интерфейс. С другой стороны, если ваш пользовательский интерфейс для youtube-dl каким-то образом даёт сбой, и вы считаете, что это связано с youtube-dl, обязательно сообщите об этом.

ИНСТРУКЦИИ ДЛЯ РАЗРАБОТЧИКОВ

Большинству пользователей не нужно собирать youtube-dl, они могут скачать сборки или получить их из своего дистрибутива.

Чтобы запустить youtube-dl в качестве разработчика, вам также не нужно ничего собирать. Просто выполните команду:

python -m youtube_dl

Для запуска теста просто вызовите свой любимый тестовый бегун или выполните тестовый файл напрямую; подойдёт любой из следующих вариантов:

python -m unittest discover
python test/test_download.py
nosetests

Если вы хотите создать сборку youtube-dl самостоятельно, вам понадобятся:

• python
• make (поддерживаются как GNU make, так и BSD make)
• pandoc
• zip
• nosetests

Добавление поддержки для нового сайта

Если вы хотите добавить поддержку для нового сайта, сначала убедитесь, что этот сайт не предназначен для нарушения авторских прав. youtube-dl не поддерживает такие сайты, поэтому пул-реквесты, добавляющие поддержку для них, будут отклонены. После того как вы убедитесь, что этот сайт распространяет свой контент легально, вы можете следовать этому краткому списку (предполагая, что ваш сервис называется yourextractor):

1. Форкните этот репозиторий.

2. Проверьте исходный код с помощью команды git clone git@github.com:YOUR_GITHUB_USERNAME/youtube-dl.git.

3. Создайте новую ветку git с помощью команды cd youtube-dl; git checkout -b yourextractor.

4. Начните с этого простого шаблона и сохраните его в файле youtube_dl/extractor/yourextractor.py:

   # coding: utf-8
   from __future__ import unicode_literals
   
   from .common import InfoExtractor
   
   
   class YourExtractorIE(InfoExtractor):
       _VALID_URL = r'https?://(?:www\.)?yourextractor\.com/watch/(?P<id>[0-9]+)'
       _TEST = {
           'url': 'http://yourextractor.com/watch/42',
           'md5': 'TODO: md5 sum of the first 10241 bytes of the video file (use --test)',
           'info_dict': {
               'id': '42',
               'ext': 'mp4',
               'title': 'Video title goes here',
               'thumbnail': 're:^https?://.*\.jpg$',
               # TODO more properties, either as:
               # * A value
               # * MD5 checksum; start the string with md5:
               # * A regular expression; start the string with re:
               # * Any Python type (for example int or float)
           }
       }
   
       def _real_extract(self, url):
           video_id = self._match_id(url)
           webpage = self._download_webpage(url, video_id)
   
           # TODO more code goes here, for example ...
           title = self._html_search_regex(r'<h1>(.+?)</h1>', webpage, 'title')
   
           return {
               'id': video_id,
               'title': title,
               'description': self._og_search_description(webpage),
               'uploader': self._search_regex(r'<div[^>]+id="uploader"[^>]*>([^<]+)<', webpage, 'uploader', fatal=False),
               # TODO more properties (see youtube_dl/extractor/common.py)
           }

5. Добавьте импорт в youtube_dl/extractor/extractors.py.

6. Запустите python test/test_download.py TestDownload.test_YourExtractor. Сначала это должно завершиться неудачей, но вы можете постоянно перезапускать его, пока не закончите. Если вы решите добавить более одного теста, то переименуйте _TEST в _TESTS и превратите его в список словарей. Тесты будут называться TestDownload.test_YourExtractor, TestDownload.test_YourExtractor_1, TestDownload.test_YourExtractor_2 и т. д.

7. Ознакомьтесь с youtube_dl/extractor/common.py, чтобы узнать о возможных вспомогательных методах и подробном описании того, что должен и может возвращать ваш экстрактор. Добавьте тесты и код для любого количества, которое вы хотите.

8. Имейте в виду, что единственными обязательными полями в info dict для успешного процесса извлечения являются id, title и либо url, либо formats, то есть это критические данные, без которых извлечение не имеет смысла. Это означает, что любое поле, кроме вышеупомянутых обязательных, следует рассматривать как необязательное, и извлечение должно быть терпимым к ситуациям, когда источники для этих полей потенциально могут быть недоступны (даже если они всегда доступны в данный момент), и оно должно быть защищено от будущего, чтобы не нарушить извлечение обязательных общих полей. Например, если у вас есть некоторый промежуточный dict meta, который является источником метаданных, и у него есть ключ summary, который вы хотите извлечь и поместить в результирующий info dict как description, вы должны быть готовы к тому, что этот ключ может отсутствовать в dict meta, то есть вы должны извлечь его как meta.get('summary'), а не meta['summary']. Аналогично, вы должны передать fatal=False, когда... Извлечение данных с веб-страницы с помощью _search_regex/_html_search_regex.

9. Проверьте код с помощью flake8.

10. Когда тесты пройдут успешно, добавьте новые файлы и зафиксируйте их, а затем отправьте результат следующим образом:

    $ git add youtube_dl/extractor/extractors.py $ git add youtube_dl/extractor/yourextractor.py $ git commit -m '[yourextractor] Add new extractor' $ git push origin yourextractor

11. Наконец, создайте запрос на включение изменений. Мы рассмотрим и объединим его.

В любом случае большое спасибо за ваш вклад!