Я знаю, что на самом деле нет единого правильного пути. Однако я обнаружил, что трудно создать структуру каталогов, которая работает хорошо и остается чистой для каждого разработчика и администратора. В большинстве проектов на github существует стандартная структура. Но он не показывает способ организовать другие файлы и все проекты на ПК.

Какой самый удобный способ организовать все эти каталоги на машине разработки? Как вы их называете, и как вы подключаете и развертываете это на сервере?

• проекты (все проекты, над которыми вы работаете)
• исходные файлы (само приложение)
• рабочая копия репозитория (я использую git)
• виртуальная среда (я предпочитаю разместить ее рядом с проектом)
• статический корень (для скомпилированных статических файлов)
• медиа-корень (для загруженных медиафайлов)
• README
• ЛИЦЕНЗИИ
• документы
• эскизы
• (пример проекта, который использует приложение, предоставленное этим проектом)
• (в случае использования sqlite)
• все, что вам обычно нужно для успешной работы над проектом

Проблемы, которые я хочу решить:

4 ответов

Есть два типа Django-проектов, которые у меня есть в моем каталоге ~/projects/ , оба имеют немного другую структуру.:

• Автономные сайты
• Подключаемые приложения

Автономный веб-сайт

Чаще всего частные проекты, но не обязательно. Обычно это выглядит так:

~/projects/project_name/ docs/ # documentation scripts/ manage.py # installed to PATH via setup.py project_name/ # project dir (the one which django-admin.py creates) apps/ # project-specific applications accounts/ # most frequent app, with custom user model __init__.py ... settings/ # settings for different environments, see below __init__.py production.py development.py ... __init__.py # contains project version urls.py wsgi.py static/ # site-specific static files templates/ # site-specific templates tests/ # site-specific tests (mostly in-browser ones) tmp/ # excluded from git setup.py requirements.txt requirements_dev.txt pytest.ini ...

Настройки

Основные настройки - производственные. Другие файлы (например, staging.py , development.py) просто импортирует все из production.py и переопределяет только необходимые переменные.

Для каждой среды существуют отдельные файлы настроек, например. производство, развитие. Я некоторые проекты, которые я тестировал (для тестировщика), (как проверка перед окончательным развертыванием) и heroku (для развертывания в heroku).

Требования

Я скорее задаю требования в setup.py напрямую. Только те, которые необходимы для среда разработки/тестирования У меня есть requirements_dev.txt .

Некоторые службы (например, heroku) требуют наличия requirements.txt в корневом каталоге.

setup.py

Полезно при развертывании проекта с помощью setuptools . Он добавляет manage.py в PATH , поэтому я могу запустить manage.py напрямую (в любом месте).

Приложения для конкретных проектов

Я использовал эти приложения в каталоге project_name/apps/ и импортировал их используя относительный импорт.

Шаблоны/статические/локальные/тестовые файлы

Я помещал эти шаблоны и статические файлы в глобальные шаблоны/статический каталог, а не внутри каждого приложения. Эти файлы обычно редактируются людьми, которым не нужен код проекта структуры или питона вообще. Если вы являетесь разработчиком полного стека, работающим в одиночку или в небольшой команде вы можете создавать шаблоны для каждого приложения/статический каталог. Это действительно просто вопрос вкуса.

То же самое относится к языку, хотя иногда удобно создавать отдельный каталог локалей.

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

каталог Tmp

В корне проекта есть временная директория, исключенная из VCS. Он имел обыкновение хранить медиа/статические файлы и базу данных sqlite во время разработки. Все в tmp может быть удален в любое время без каких-либо проблем.

Virtualenv

Я предпочитаю virtualenvwrapper и поместить все venvs в каталог ~/.venvs но вы можете разместить его внутри tmp/ , чтобы сохранить его вместе.

Шаблон проекта

Я создал шаблон проекта для этой установки, django-start-template

Развертывание

Развертывание этого проекта выполняется следующим образом:

Source $VENV/bin/activate export DJANGO_SETTINGS_MODULE=project_name.settings.production git pull pip install -r requirements.txt # Update database, static files, locales manage.py syncdb --noinput manage.py migrate manage.py collectstatic --noinput manage.py makemessages -a manage.py compilemessages # restart wsgi touch project_name/wsgi.py

Вы можете использовать rsync вместо git , но все же вам нужно запустить пакет команд для обновления вашей среды.

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

Эскизы и черновики

Черновик шаблонов, которые я размещаю внутри глобального каталога templates/ . Я думаю, можно создать папку sketches/ в корне проекта, но еще не использовали ее.

Подключаемое приложение

Эти приложения обычно готовятся к публикации как открытые. Я привел пример ниже django-forme

~/projects/django-app/ docs/ app/ tests/ example_project/ LICENCE MANIFEST.in README.md setup.py pytest.ini tox.ini .travis.yml ...

Название каталогов понятно (надеюсь). Я помещал тестовые файлы вне каталога приложения, но это действительно неважно. Важно предоставить README и setup.py , поэтому пакет легко устанавливается через pip .

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

Проекты
У меня есть основная папка в моем личном каталоге, где я просматриваю все объекты, на которых я работаю.

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

Project_repository_folder/ .gitignore Makefile LICENSE.rst docs/ README.rst requirements.txt project_folder/ manage.py media/ app-1/ app-2/ ... app-n/ static/ templates/ project/ __init__.py settings/ __init__.py base.py dev.py local.py test.py production.py ulrs.py wsgi.py

Репозиторий
Git или Mercurial, по-видимому, являются самыми популярными системами управления версиями среди разработчиков Django. И самые популярные услуги хостинга для резервных копий GitHub и Bitbucket .

Виртуальная среда
Я использую virtualenv и virtualenvwrapper. После установки второго нужно настроить рабочий каталог. Mine находится в каталоге my/home/envs, так как это рекомендуется в руководстве по установке virtualenvwrapper. Но я не думаю, что самое главное, где оно размещено. Самое главное при работе с виртуальными средами - обновлять файл requirements.txt.

Pip freeze -l > requirements.txt

Статический корень
Папка проекта

Корень СМИ
Папка проекта

README
Корень репозитория

ЛИЦЕНЗИЯ
Корень репозитория

Документы
Корень репозитория. Эти пакеты python могут помочь вам упростить вашу документацию:

Эскизы

Примеры

База данных

Мне не нравится создавать новый каталог settings/ . Я просто добавляю файлы с именем settings_dev.py и settings_production.py , поэтому мне не нужно редактировать BASE_DIR . Приведенный ниже подход увеличивает структуру по умолчанию вместо изменения.

Mysite/ # Project conf/ locale/ en_US/ fr_FR/ it_IT/ mysite/ __init__.py settings.py settings_dev.py settings_production.py urls.py wsgi.py static/ admin/ css/ # Custom back end styles css/ # Project front end styles fonts/ images/ js/ sass/ staticfiles/ templates/ # Project templates includes/ footer.html header.html index.html myapp/ # Application core/ migrations/ __init__.py templates/ # Application templates myapp/ index.html static/ myapp/ js/ css/ images/ __init__.py admin.py apps.py forms.py models.py models_foo.py models_bar.py views.py templatetags/ # Application with custom context processors and template tags __init__.py context_processors.py templatetags/ __init__.py templatetag_extras.py gulpfile.js manage.py requirements.txt

• Перевод

В этом руководстве мы рассмотрим основные ошибки Django-разработчиков и узнаем, как их избежать. Статья может быть полезна даже опытным разработчикам, потому что и они совершают такие ошибки, как поддержка неподъёмно больших настроек или конфликтов имён в статических ресурсах.

Django - бесплатный сетевой open source Python-фреймворк, помогающий решать распространённые в разработке проблемы. Он позволяет создавать гибкие, хорошо структурированные приложения. В Django уже из коробки есть много современных возможностей. Например, для меня такие фичи, как Admin, инструмент Object Relational Mapping (ORM), Routing и Templating, делают Django первым кандидатом при выборе инструментария для разработки. Создание приложения требует много сил, и, наслаждаясь своим делом, как и любой разработчик, я хочу тратить как можно меньше времени на рутинные задачи. Django сильно в этом помогает, не заставляя жертвовать гибкостью приложения.

Киллер-фича Django - мощный конфигурируемый админский интерфейс, который автоматически (автомагически?) генерируется на основе схемы вашей модели и моделей админки. Чувствуешь себя прямо-таки волшебником. С помощью интерфейса Admin пользователь может конфигурировать много вещей, в их числе - список управления доступом (access control list, ACL), разрешения и действия на уровне строк (row-level), фильтры, порядки сортировки (orders), виджеты, формы, дополнительные URL-хелперы и многое другое. Я считаю, что админка нужна каждому приложению. Это лишь вопрос времени, когда такая панель понадобится вашему основному приложению. В Django она создаётся быстро и удобно.

Также в Django есть мощная ORM, из коробки работающая со всеми главными базами данных. Она «ленива»: в отличие от других ORM, обращается к БД только по мере необходимости. В ней есть поддержка основных SQL-инструкций (и функций), которые вы можете использовать из своего исходного Python-кода наряду со всеми остальными возможностями языка.
В Django очень гибкий и мощный шаблонизатор (templating engine). Доступны многие стандартные фильтры и метки (tags), также можно создавать свои собственные. Django поддерживает другие движки как собственные шаблоны, предоставляет API для лёгкой интеграции с другими движками посредством стандартных shortcut-функций для обработки шаблонов.

Фреймворк имеет и много других важных возможностей вроде URL-роутера, который парсит входящие запросы и генерирует новые URL на основе схемы роутинга. В целом Django приятен в работе, и, когда вам понадобится помощь, просто почитайте документацию .

Ошибка № 1. Использование для проектных зависимостей глобального окружения Python

Не используйте глобальное окружение Python для зависимостей вашего проекта, потому что это может привести к возникновению конфликтов зависимостей. Python не умеет работать с несколькими версиями пакетов одновременно. Это станет проблемой, если разным проектам нужны разные, несовместимые версии одного пакета.

Обычно такую ошибку допускают новички в Python- и Django-разработке, не знающие об особенностях изоляции окружения Python.

Есть много способов изолировать окружение, наиболее часто встречаются такие:

• virtualenv : пакет Python, генерирующий папку с окружением. Содержит скрипт для (де)активации окружения и управления установленными в нём пакетами. Это мой любимый и самый простой метод. Обычно я создаю окружение поближе к папке проекта.
• virtualenvwrapper : пакет Python, глобально устанавливающий набор инструментов для создания/удаления/активации и т. д. виртуальных окружений и предоставляющий доступ к этому набору. Все окружения хранятся в одной папке (её можно переписать с помощью переменной WORKON_HOME). Я не вижу преимуществ в использовании virtualenvwrapper вместо virtualenv .
• Виртуальные машины : нет лучшей изоляции, чем целая виртуальная машина, выделенная под ваше приложение. Есть масса доступных инструментов, например VirtualBox (бесплатный), VMware , Parallels и Proxmox (мой фаворит, есть бесплатная версия). В сочетании с инструментом автоматизации виртуальных машин вроде Vagrant это может оказаться очень мощным решением.
• Контейнеры : в последние годы я почти в каждом проекте использую Docker , особенно в новых проектах, начинаемых с нуля. Docker - невероятный инструмент с множеством возможностей. Для его автоматизации доступна куча сторонних инструментов. В Docker есть кеширование уровней (layer caching), позволяющее крайне быстро пересоздавать контейнеры. В них я использую глобальное окружение Python, потому что каждый контейнер имеет собственную файловую систему и проекты изолируются на высоком уровне. Docker позволяет новым членам команды быстрее начинать работу над проектом, особенно если у них есть опыт работы с этой технологией.

Ошибка № 2. Отсутствие привязки зависимостей в файле requirements.txt

Каждый новый проект Python должен начинаться с файла requirements.txt и нового изолированного окружения. Обычно вы с помощью pip/easy_install устанавливаете все пакеты, не забывая о requirements.txt . Обычно проще (возможно , правильнее) развёртывать проекты на серверах или на машинах членов команды.

Также важно в файле requirements.txt выполнять привязку (pin) конкретных версий ваших зависимостей. Обычно разные версии пакета предоставляют разные модули, функции и параметры функций. Даже в младших версиях изменения зависимостей могут оказаться такими, что это сломает ваш пакет. Это очень серьёзная проблема, если у вас живой проект и вы планируете регулярно его развёртывать, так как без системы управления версиями ваша сборочная система всегда будет устанавливать последнюю доступную версию пакета.

В production всегда выполняйте привязку пакетов! Я для этого использую очень хороший инструмент pip-tools . Он предоставляет набор команд, помогающих управлять зависимостями. Инструмент автоматически генерирует requirements.txt , в котором привязаны не просто ваши зависимости, а вообще всё дерево, т. е. и зависимости ваших зависимостей.

Иногда нужно обновить какие-то пакеты в списке зависимостей (например, только фреймворк или утилиту). Если вы прибегаете к pip freeze, то не знаете, какие зависимости используются какими пакетами, и поэтому не можете их обновить. Инструмент pip-tools автоматически привязывает пакеты в соответствии с привязанными вами зависимостями, и поэтому он автоматически решает, какие пакеты нужно обновить. А благодаря используемым комментариям в requirements.txt вы всегда знаете, какой пакет пришёл из какой зависимости.

Если быть ещё более осторожным, то можно делать бекап исходных файлов ваших зависимостей. Храните копию в своей файловой системе, Git-папке, S3-папке, FTP, SFTP - где угодно, лишь бы под рукой. Бывают ситуации, когда исключение из списка относительно небольшого пакета ломает большое количество пакетов в npm . Pip позволяет скачивать все необходимые зависимости в виде исходных файлов. Почитайте об этом подробнее, выполнив команду pip help download .

Ошибка № 3. Использование старомодных Python-функций вместо представлений-классов (Class-based Views)

Иногда целесообразно использовать в файле приложения views.py маленькие Python-функции, особенно для тестовых или утилитарных представлений. Но обычно в приложениях нужно использовать представления на основе классов (CBV).

CBV - это представления общего назначения, предоставляющие абстрактные классы, реализующие распространённые задачи веб-разработки. CBV созданы профессионалами и покрывают большинство востребованных моделей поведения. У них есть прекрасно структурированный API, и CBV подарят вам возможность наслаждаться всеми преимуществами ООП. Ваш код будет чище и читабельнее. Забудьте о трудностях использования стандартных функций представления (view functions) Django для создания списков, CRUD-операций, обработки форм и т. д. Можно просто расширять подходящий CBV под ваше представление и переопределять (override) функции или свойства класса, конфигурирующие поведение представления (обычно функция возвращает свойство, и вы можете добавить в неё любую логику, которая способна превратить ваш код в спагетти, если вместо CBV вы прибегнете к функциям представления).

Например, можно использовать в проекте разные миксины, которые переопределяют основные модели поведения CBV: создание контекстов представлений, проверка авторизации на уровне строк (on the row level), автосоздание путей шаблонов на основе структур приложения, интегрирование умного кеширования и многое другое.

Я создал пакет Django Template Names , который стандартизирует имена шаблонов для ваших представлений на основе имени приложения и имени класса представления. Я пользуюсь им каждый день и экономлю кучу времени при выборе имён. Просто вставьте миксин в свой CBV - class Detail(TemplateNames, DetailView): - и он начнёт работать! Конечно, можете переопределить мои функции и добавить мобильные адаптивные шаблоны, другие шаблоны для user-agent’ов или что-нибудь ещё.

Ошибка № 4. Написание «толстых» (fat) представлений и «тонких» (skinny) моделей

Если у вас логика приложения перенесена из модели в представления, это означает, что в представлениях находится код, принадлежащий модели. То есть представления становятся «толстыми», а модель - «тонкой».

А нужно писать «толстые» модели и «тонкие» представления.

Разбейте логику по маленьким методам в модели. Это позволит использовать их многократно и из многочисленных источников (админский пользовательский интерфейс, пользовательский интерфейс фронтенда, конечные точки API, многочисленные представления). Это займёт всего несколько строк кода, и вам не придётся копипастить кучу строк. Когда в следующий раз будете писать функциональность отправки письма пользователю, расширьте модель с помощью email-функции, а не пишите логику в контроллере.

Это сделает ваш код более удобным для модульного тестирования, потому что вы сможете протестировать логику электронной почты в одном месте, а не делать это в каждом контроллере. Подробнее об этой проблеме почитайте в Django Best Practices . Решение простое: пишите «толстые» модели и «тонкие» представления. Начните это делать уже в следующем проекте или рефакторьте текущий.

Ошибка № 5. Огромный, неповоротливый файл настроек

Даже в новом файле настроек Django-проекта этих настроек содержится множество. А в реальных проектах файл разрастается до 700+ строк, которые трудно сопровождать, особенно когда окружениям разработки, продакшена и стейджинга нужны разные конфигурации.

Вы можете вручную разделить конфигурационный файл и создать отдельные загрузчики, но я хочу порекомендовать отличный, хорошо протестированный Python-пакет Django Split Settings , соавтором которого я являюсь.

Пакет предоставляет две функции - optional и include , которые поддерживают подстановки (wildcards) для путей и импортируют ваши конфигурационные файлы в тот же контекст. Благодаря этому можно просто создавать конфигурации с помощью объявления конфигурационных записей в ранее загруженных файлах. Пакет никак не влияет на производительность Django и может применяться в любых проектах.

Вот пример минимальной конфигурации:

from split_settings.tools import optional, include include("components/base.py", "components/database.py", "components/*.py", # the project different envs settings optional("envs/devel/*.py"), optional("envs/production/*.py"), optional("envs/staging/*.py"), # for any local settings optional(‘local_settings.py"),)

Ошибка № 6. Приложение всё-в-одном, плохая структура приложения и некорректное размещение ресурсов

Любой Django-проект состоит из нескольких приложений. В терминологии Django приложение - это Python-проект, содержащий как минимум файлы __init__.py и models.py . В последних версиях Django models.py больше не нужен, достаточно только __init__.py .

Django-приложения могут содержать Python-модули, характерные для Django модули (представления, URL’ы, модели, админскую панель, формы, метки шаблонов и т. д.), статичные файлы, шаблоны, миграции базы данных, команды управления, модульные тесты и пр. Нужно разбивать своё монолитное приложение на маленькие многократно используемые приложения с простой логикой.

У вас должна быть возможность полностью описать назначение приложения одним-двумя короткими предложениями. Например: «Позволяет пользователю зарегистрировать и активировать по почте свой аккаунт».

• Статичные файлы: project/apps/appname/static/appname/
• Метки шаблона: project/apps/appname/templatetags/appname.py
• Файлы шаблона: project/apps/appname/templates/appname/

Всегда добавляйте имена приложений в виде префиксов в названия подпапок, потому что все статические папки объединяются в одну. И если два или более приложений имеют файл js/core.js , то последнее приложение в settings.INSTALLED_APPLICATIONS переопределит все предыдущие. Однажды я столкнулся с таким багом в своём проекте и потратил около шести часов на отладку, пока не сообразил, что другой разработчик переопределил мой static/admin/js/core.js , потому члены команды реализовали кастомную админскую SPA-панель и дали своим файлам такие же имена.

Вот пример структуры для портального приложения, содержащего много ресурсов и Python-модулей.

root@c5b96c395cfb:/test# tree project/apps/portal/ project/apps/portal/ ├── __init__.py ├── admin.py ├── apps.py ├── management │ ├── __init__.py │ └── commands │ ├── __init__.py │ └── update_portal_feeds.py ├── migrations │ └── __init__.py ├── models.py ├── static │ └── portal │ ├── css │ ├── img │ └── js ├── templates │ └── portal │ └── index.html ├── templatetags │ ├── __init__.py │ └── portal.py ├── tests.py ├── urls.py └── views.py 11 directories, 14 files

Благодаря такой структуре вы можете в любой момент экспортировать приложение в другой Python-пакет и снова его использовать. Можете даже опубликовать его в PyPi в качестве open source пакета или переместить в другую папку. У вас получится примерно такая структура проекта:

root@c5b96c395cfb:/test# tree -L 3 . ├── deploy │ ├── chef │ └── docker │ ├── devel │ └── production ├── docs ├── logs ├── manage.py ├── media ├── project │ ├── __init__.py │ ├── apps │ │ ├── auth │ │ ├── blog │ │ ├── faq │ │ ├── pages │ │ ├── portal │ │ └── users │ ├── conf │ ├── settings.py │ ├── static │ ├── templates │ ├── urls.py │ └── wsgi.py └── static └── admin ├── css ├── fonts ├── img └── js 25 directories, 5 files

Конечно, реальный проект будет сложнее, но такая структура упрощает и делает более прозрачными многие аспекты.

Ошибка № 7. STATICFILES_DIRS и STATIC_ROOT смущают новичков в Django-разработке

Статичные файлы - это ресурсы (assets), которые не меняются по мере использования приложения. Например, JavaScript, CSS, изображения, шрифты и т. д. В Django они «накапливаются» в публичной директории в ходе развёртывания.

В режиме разработки - python manage.py runserver - Django ищет статичные файлы с помощью настройки STATICFILES_FINDERS . По умолчанию он пытается найти запрошенный файл в папках, перечисленных в STATICFILES_DIRS . Если не находит, то ищет с помощью django.contrib.staticfiles.finders.AppDirectoriesFinder , которая проверяет папку static каждого установленного в проекте приложения. Такая схема позволяет писать многократно используемые приложения, поставляемые со своими собственными статичными файлами.

В production вы раздаёте статичные данные посредством отдельного веб-сервера, например nginx. Он ничего не знает о структуре приложений проекта Django или о том, по каким папкам распределены ваши статичные файлы. К счастью, Django предоставляет нам команду управления сбором статичных данных (collect static management command) - python manage.py collectstatic , которая проходит по STATICFILES_FINDERS и копирует все статичные файлы из папок static приложений, а также из папок, перечисленных в STATICFILES_DIRS , в заданную вами в STATIC_ROOT директорию. Это позволяет разрешать (resolution) ресурсы в виде статичных данных с помощью той же логики, что и у Django-сервера в режиме разработки, и собирать в одном месте для веб-сервера все статичные файлы.

Не забудьте выполнить collectstatic в вашем production-окружении!

Ошибка № 8. Использование в production STATICFILES_STORAGE по умолчанию и загрузчиков Django-шаблонов

Давайте поговорим об управлении ресурсами (asset) production-окружения. Мы можем обеспечить наилучший UX, если воспользуемся политикой «у ресурсов не истекает срок действия» (assets never expire) (подробнее о ней можно почитать ). Это означает, что все наши статичные файлы должны быть закешированы браузерами на недели, месяцы или даже годы. Иными словами, пользователи должны лишь единожды скачивать ресурсы!

Классная идея, и её можно реализовать всего в несколько строк в nginx-конфигурации для нашей папки со статичными файлами. Но что насчёт проверки актуальности кеша? Если пользователь лишь один раз скачивает наш ресурс, то что делать в том случае, если вы обновите логотип, шрифты, JavaScript или цвет текста в меню? Для решения этой задачи вам нужно при каждом развёртывании генерировать уникальные URL’ы и имена для каждого статичного файла!

Для этого можно использовать ManifestStaticFilesStorage в качестве STATICFILES_STORAGE (будьте осторожны, хеширование включается только в режиме DEBUG=false) и выполнить команду collectstatic . Это приведёт к снижению количества запросов ресурсов у вашего production-сайта и сделает его отрисовку гораздо быстрее.

Клёвая фича Django - закешированный загрузчик шаблона. Он не перезагружается и парсит файлы шаблона при каждой его отрисовке. Парсинг шаблона - очень дорогая операция, она требует много вычислительных ресурсов. По умолчанию Django-шаблоны парсятся при каждом запросе, а это плохо, особенно в production, где за короткий промежуток времени могут обрабатываться тысячи запросов.

В разделе конфигурации cached.Loader можно найти хороший пример и подробности решения проблемы. Не используйте загрузчик в режиме разработки, потому что он не перезагружает отпарсенные шаблоны из файловой системы. Вам понадобится перезапускать свой проект, используя python manage.py startapp , при каждом изменении шаблона. При разработке это может раздражать, зато идеально для production-окружения.

Ошибка № 9. Чистый Python для утилит или скриптов

У Django есть отличная фича - команды управления . Используйте их вместо изобретения велосипеда в виде написания скриптов на чистом Python для утилит вашего проекта.

Также обратите внимание на пакет Django Extensions , представляющий собой коллекцию кастомных расширений для Django. Возможно, кто-то уже реализовал ваши команды! Существует много распространённых целевых команд.

Ошибка № 10. Велосипедостроение

Для Django и Python есть тысячи готовых решений. Обратитесь к поисковикам, прежде чем писать что-то, что вовсе не уникально. Вероятно, уже есть подходящее решение.

Не надо усложнять. Сначала - гуглим! Установите найденный качественный пакет, сконфигурируйте, расширьте и интегрируйте в свой проект. И если есть возможность, внесите свой вклад в open source.

Вот вам для начала список моих собственных пакетов для Django:

• Django Macros URL : с помощью макросов облегчает написание (и чтение) URL-паттернов в Django-приложениях.
• Django Templates Names : маленький миксин, помогает легко стандартизировать имена ваших CBV-шаблонов.
• Django Split Settings : позволяет распределить Django-настройки по нескольким файлам и директориям. Легко переопределяет и модифицирует настройки. Использует подстановки (wildcards) в путях файлов и помечает файлы настроек как опциональные.

Don’t repeat yourself (DRY)!

Я сторонник DRY-концепции, поэтому создал Django skeleton - удобный инструмент с рядом приятных функций уже из коробки:

• Docker-образы для разработки/production, управляемые docker-compose, что позволяет легко оркестрировать списком контейнеров.
• Простой Fabric-скрипт для развёртывания в production.
• Конфигурация для пакета Django Split Settings с настройками базы и локальных источников.
• Интегрированный в проект Webpack - при выполнении команды collectstatic Django соберёт только папку dist.
• Сконфигурированы все основные Django-настройки и фичи вроде кешируемых в production Django-шаблонов, хешированных статичных файлов, интегрированного тулбара для отладки, журналирования и т. д.

Это готовый к использованию Django-скелет для вашего следующего проекта, создаваемого с нуля. Надеюсь, он сэкономит вам кучу времени. Webpack имеет минимальную базовую конфигурацию, но также в него с помощью SASS установлены заранее сконфигурированные для обработки файлы.scss.

Теги:

• python
• django
• никто не читает теги

Добавить метки

Django - это Open Source фреймворк для создания веб-приложений различной сложности. Одним из основных преимуществ Django является то, что вам нужно позаботиться только о логике вашего будущего приложения, остальное сделает Django.

Мы создадим веб-приложение, у которого будет панель администратора и возможность загружать загадки, а у пользователей, соответственно, возможность отвечать на них. Во время разработки будут использоваться Python 3.4.3 и Django 1.9.1.

Устанавливаем Django

Делается это очень просто, в командной строке нужно написать: pip install Django==1.9.1 .

Создаем проект

Если вы правильно установили Django, то после запуска django-admin --version вы увидите текущую версию фреймворка. Теперь создадим проект. Это можно сделать следующим образом: django-admin startproject django_example .

Как только создание проекта будет завершено, взглянем на директорию нашего проекта:

• django_example/__init__.py - пустой файл, который говорит Python, что данная директория должна восприниматься в качестве пакета.
• django_example/settings.py содержит конфигурацию нашего проекта.
• django_example/urls.py - здесь объявляются URL.
• django_example/wsgi.py - с помощью него приложение может работать с веб-сервером по протоколу WSGI.
• manage.py позволяет взаимодействовать с проектом.

Теперь пришло время запустить наше приложение. Для этого в командной строке нужно написать python manage.py runserver . После этого в адресной строке браузера нужно написать: http://127.0.0.1:8000/ . Если вы увидели «You have unapplied migrations; your app may not work properly until they are applied.», то не волнуйтесь, мы вернемся к этому чуть позже.

Создаем приложение

Определим различие между проектом и приложением. Приложение - это программа, которая что-то делает, а проект - это группа приложений.

Итак, приступим к созданию приложения. Это делается следующим образом: python manage.py startapp riddles .
Как только приложение создано, давайте напишем простой вид, по правилам Django все виды должны храниться в файле views.py .

riddles/views.py

From django.http import HttpResponse def index(request): return HttpResponse("Hello, World!")

Теперь, чтобы привязать наш вид к URL, создадим файл urls.py .

riddles/urls.py

From django.conf.urls import url from . import views app_name = "riddles" urlpatterns = [ url(r"^$", views.index, name="index"), ]

В urls.py мы должны написать следующее:

django_example/urls.py

From django.conf.urls import include, url from django.contrib import admin urlpatterns = [ url(r"^riddles/", include("riddles.urls")), url(r"^admin/", admin.site.urls), ]

Теперь, если мы запустим наше приложение http://127.0.0.1:8000/riddles/ , мы увидим «Hello, World!».

Установка базы данных

По умолчанию в Django используется SQLite, если она вас не устраивает, то вы с нашей статьей, в которой мы рассказываем, как безболезненно перейти с SQLite на MySQL.

Теперь откроем django_example/settings.py и взглянем на переменную INSTALLED_APPS , она хранит все приложения, которые активны в текущем проекте. По умолчанию она содержит:

• django.contrib.admin - админка, скоро мы ей воспользуемся.
• django.contrib.auth - система аутентификации.
• django.contrib.contenttypes - фреймворк для content types.
• django.contrib.sessions - сессионный фреймворк.
• django.contrib.messages - фреймворк для отправки сообщений.
• django.contrib.staticfiles - фреймворк для работы со статичными файлами.

Некоторые из этих приложений используют базы данных, но они еще не установлены, поэтому мы и видели «You have unapplied migrations; your app may not work properly until they are applied.». Поправить это можно следующим образом: python manage.py migrate . Вы должны увидеть следующее:

Operations to perform: Apply all migrations: admin, sessions, auth, contenttypes Running migrations: Rendering model states... DONE Applying contenttypes.0001_initial... OK Applying auth.0001_initial... OK Applying admin.0001_initial... OK Applying admin.0002_logentry_remove_auto_add... OK Applying contenttypes.0002_remove_content_type_name... OK Applying auth.0002_alter_permission_name_max_length... OK Applying auth.0003_alter_user_email_max_length... OK Applying auth.0004_alter_user_username_opts... OK Applying auth.0005_alter_user_last_login_null... OK Applying auth.0006_require_contenttypes_0002... OK Applying auth.0007_alter_validators_add_error_messages... OK Applying sessions.0001_initial... OK

Теперь создадим нашу модель. Для начала создадим Riddle и Option . В Riddle будет содержаться загадка, в Option - один из возможных ответов на нее.

riddles/models.py

From django.db import models class Riddle(models.Model): riddle_text = models.CharField(max_length=255) pub_date = models.DateTimeField("date published") class Option(models.Model): riddle = models.ForeignKey(Riddle, on_delete=models.CASCADE) text = models.CharField(max_length=255) correct = models.BooleanField(default=False)

Данная модель обеспечивает Django информацией, необходимой для создания схемы базы данных и database-access API для доступа к объектам. Теперь нам нужно привязать наше приложение к нашему проекту, делается это следующим образом:

django_example/settings.py

INSTALLED_APPS = [ "riddles.apps.RiddlesConfig", "django.contrib.admin", "django.contrib.auth", "django.contrib.contenttypes", "django.contrib.sessions", "django.contrib.messages", "django.contrib.staticfiles", ]

После этого нужно сделать миграцию: python manage.py makemigrations riddles . Вы должны увидеть следующее:

Migrations for "riddles": 0001_initial.py: - Create model Option - Create model Riddle - Add field riddle to option

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

Проверить, что сделает миграция, можно так: python manage.py sqlmigrate riddles 0001 (0001 - версия миграции, которую мы хотим проверить). На выходе мы получим:

BEGIN; -- -- Create model Option -- CREATE TABLE "riddles_option" ("id" integer NOT NULL PRIMARY KEY AUTOINCREMENT, "text" varchar(255) NOT NULL, "correct" bool NOT NULL); -- -- Create model Riddle -- CREATE TABLE "riddles_riddle" ("id" integer NOT NULL PRIMARY KEY AUTOINCREMENT, "riddle_text" varchar(255) NOT NULL, "pub_date" datetime NOT NULL); -- -- Add field riddle to option -- ALTER TABLE "riddles_option" RENAME TO "riddles_option__old"; CREATE TABLE "riddles_option" ("id" integer NOT NULL PRIMARY KEY AUTOINCREMENT, "text" varchar(255) NOT NULL, "correct" bool NOT NULL, "riddle_id" integer NOT NULL REFERENCES "riddles_riddle" ("id")); INSERT INTO "riddles_option" ("riddle_id", "id", "text", "correct") SELECT NULL, "id", "text", "correct" FROM "riddles_option__old"; DROP TABLE "riddles_option__old"; CREATE INDEX "riddles_option_a7c97949" ON "riddles_option" ("riddle_id"); COMMIT;

Заметьте, что команда sqlmigrate нужна только для проверки, каждый раз ее запускать необязательно.

Теперь мы можем начать пользоваться панелью администратора. Но для этого нам нужен пользователь. Создать его можно следующим образом: python manage.py createsuperuser . После этого запускаем сервер, если он не запущен, и переходим на http://127.0.0.1:8000/admin/ . Вы увидите следующее:

Теперь дадим админу возможность изменять наши модели. Делается это так:

riddles/admin.py

From django.contrib import admin from .models import Option, Riddle admin.site.register(Riddle) admin.site.register(Option)

Вот что получится в итоге:

Возьмите небольшую паузу и поиграйтесь с панелью администратора. Вы будете приятно удивлены тем, что умеет Django.

Главная страница

Что нам нужно для создания главной страницы?

• Templates: скелет нашей страницы.
• Views: функция на Python для отображения контента.

Начнем с шаблонов. Создадим папку templates внутри папки riddle , а в ней создадим index.html .

riddles/templates/index.html

Available Riddles

{% if message %}

{{ message }}

• {{ riddle.riddle_text }}
{% endfor %}

{% else %} {% endif %}

Теперь создадим макет для ответов:

{{ riddle.riddle_text }}

{% if error_message %}

{{ error_message }}

{% endif %}

{{ option.text }}
{% endfor %}

Здесь мы используем csrf_token , он нужен для защиты от межсайтовой подделки запроса , каждая внутренняя форма должна его использовать. Теперь напишем виды для рендеринга наших шаблонов:

riddles/views.py

From django.http.response import HttpResponse from django.shortcuts import get_object_or_404, render from .models import Riddle, Option def index(request): return render(request, "index.html", {"latest_riddles": Riddle.objects.order_by("-pub_date")[:5]}) def detail(request, riddle_id): return render(request, "answer.html", {"riddle": get_object_or_404(Riddle, pk=riddle_id)}) def answer(request, riddle_id): riddle = get_object_or_404(Riddle, pk=riddle_id) try: option = riddle.option_set.get(pk=request.POST["option"]) except (KeyError, Option.DoesNotExist): return render(request, "answer.html", {"riddle": riddle, "error_message": "Option does not exist"}) else: if option.correct: return render(request, "index.html", {"latest_riddles": Riddle.objects.order_by("-pub_date")[:5], "message": "Nice! Choose another one!"}) else: return render(request, "answer.html", {"riddle": riddle, "error_message": "Wrong Answer!"})

Давайте пройдемся по каждой функции отдельно:

• index: Index использует функцию render . На вход она получает HttpRequest, местонахождение шаблона и его содержимое, а возвращает HttpResponse с окончательным html.
• detail: Detail делает практически то же самое, но только функция get_object_or_404 возвращает HttpResponse404, если нужный объект не был найден.
• answer: Answer ищет предоставленную загадку (и возвращает 404, если она не найдена) и проверяет правильность ответа.

Теперь добавим наши функции в urls.py:

riddles/urls.py

From django.conf.urls import url from . import views app_name = "riddles" urlpatterns = [ url(r"^$", views.index, name="index"), url(r"^(?P+)/$", views.detail, name="detail"), url(r"^(?P+)/answer/$", views.answer, name="answer") ]

Добавим немного стилей

Для начала создадим директорию static , а в ней создадим файл main.css .

riddles/static/main.css

Body{ margin:40px auto; max-width:650px; line-height:1.6; font-size:18px; color:#444; padding:0 10px; } h1,h2,h3{ line-height:1.2; text-align: center; } a { color: blue; } form { margin: 0 auto; padding: 1em; border: 1px solid #CCC; border-radius: 1em; } form div + div { margin-top: 1em; } label { display: inline-block; text-align: center; width: 40%; } input { font: 1em sans-serif; -moz-box-sizing: border-box; box-sizing: border-box; border: 1px solid #999; width: 50%; } input:focus { border-color: #000; } p, div.button { text-align: center; } p.error-message { color: lightcoral; }

Немного изменим наши шаблоны:

riddles/templates/index.html

{% load staticfiles %}

Available Riddles

{% if message %}

{{ message }}

{% endif %} {% if latest_riddles %}

{% for riddle in latest_riddles %}
• {{ riddle.riddle_text }}
{% endfor %}

{% else %}

No riddles are available right now.

{% endif %}

riddles/templates/answer.html

{% load staticfiles %}

{{ riddle.riddle_text }}

{% if error_message %}

{{ error_message }}

{% endif %}

{% csrf_token %} {% for option in riddle.option_set.all %} {{ option.text }}
{% endfor %}

Первая строка загружает статические файлы, потом мы используем {% static "#" %} , где # - путь к вашему файлу. Аналогичная процедура проводится и для JavaScript.

Теперь вы можете создавать свои собственные приложения на Django.

Какая оптимальная структура для ваших Django приложений, настроек и других ассоциированных директорий?

Когда вышла Django 1.4 она включала обновленую структуру проекта, которая прошла долгий путь, чтобы стать основной, но здесь, собраны некоторые улучшения, чтобы сделать структуру лучше.

Подобный вопрос нам задают постоянно, поэтому я хочу потратить немного времени и рассказать все наше отношение к этому, чтобы всех клиентов можно было отправлять к этому документу. Эта заметка написана для Django 1.7.1, но может быть легко применена для всех Django версий выше 1.4.

Почему данная структура лучше

1. Позволяет вам держать, пересобирать и переисопльзовать индивидальные Django приложения для использования в других проектах. Ведь не всегда создаваемое приложение делается реиспользуемым, но в будущем, может вырасти в такое. Построение проекта описываемым способом, позволяет писать реиспользуемые приложения сразу же, а не только, когда потребуется.
2. Поощряет разработку реиспользуемых приложений
3. Индивидуальных настройки для каждого окружения. Никаких больше “if DEBUG ==True” в едином монолитном файле настроек. Это позволяет легко видеть, какие настройки общие и что переопределяется на каждом окружении.
4. Индивидульный список pip зависимостей для каждого окружения.
5. Шаблоны проекта и статические файлы, если требуется, могут переопределять значения по умолчанию уровня приложений.
6. Небольшие более детальные тестовые файлы, которые легче для чтения и понимания.

Предположим, у вас есть 2 приложения blog и users и 2 окружения dev и prod , значит, ваш проект должен иметь следующий вид:

myproject/ manage.py myproject/ __init__.py urls.py wsgi.py settings/ __init__.py base.py dev.py prod.py blog/ __init__.py models.py managers.py views.py urls.py templates/ blog/ base.html list.html detail.html static/ … tests/ __init__.py test_models.py test_managers.py test_views.py users/ __init__.py models.py views.py urls.py templates/ users/ base.html list.html detail.html static/ … tests/ __init__.py test_models.py test_views.py static/ css/ … js/ … templates/ base.html index.html requirements/ base.txt dev.txt test.txt prod.txt

Продолжение этой статьи расскажет, как привести свой проект к такой структуре и почему она лучше.

Текущая структура по умолчанию

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

Если вы запустите свой проект с помощью команды django-admin.py startproject foo , вы получите следующую структуру:

foo/ manage.py foo/ __init__.py settings.py urls.py wsgi.py

Эта схема очень хороша для старта. У нас есть корневая директория foo , которая содержит наш manage.py и директорию проекта foo/foo . Эту директорию можно добавить в свою систему контроля версия, например в git.

Вы можете подумать, что директория foo/foo начало проекта, где все кроме этого это Django приложения или вспомогательные файлы относящиеся к проекту.

Исправляем настройки

Наша первая миссия, это исправить ваш плохой файл настроек. Мы показали данную архитектуру нашим клиентам и были впечатлены, как мало людей знают, что такое можно реализовать. Я виню в этом тот факт, что каждый знает, что файл настроек это просто Python код, но они не думают о нем, как о Python коде.

И так, давайте исправим наши настройки. Для нашего проекта foo реализуем схему с 4 окружениями: dev, stage, jenkins, и production. Давайте дадим каждому окружения свой собственный файл. Процесс для этого следующий:

1. В foo/foo создадим директорию settings и пустой файл __init__.py внутри нее.
2. Перенесем foo/foo/settings.py в foo/foo/settings/base.py
3. Создадим индивидуальные файлы dev.py , stage.py , jenkins.py , и production.py в foo/foo/settings/ . Каждый из этих файлов должен содержать следующее

from base import *

Так, почему это важно? Для локальной разработки вам требуется DEBUG =True , но вы также, можете случайно выкатить это и в продакшен, поэтому просто откройте foo/foo/settings/production.py и после первой строки импорта вставьте DEBUG =False . Теперь, ваш продакшен сайт защищен от такой случайности.

Что еще вы можете настроить? Достаточно очевидно, что для каждого окружения вы захотите иметь различные базы данных, например на разных хостах. Для этого, просто внесите эти настройки в соответствубщие файлы настроек.

Использование этих настроек

Использование этих настроект очень легкое и не зависит от того, какой метод вы предпочитаете. Для использования настроек определенного окружения, вы должны всего лишь:

export DJANGO_SETTINGS_MODULE = “foo.settings.jenkins”

И бум, вы теперь используете jenkins настройки.

Или вы можете предпочесть передачу настроек через коммандную строку:

./manage.py migrate -settings= foo.settings.production

Или используя gunicorn:

gunicorn -w 4 -b 127.0.0.1:8001 -settings= foo.settings.dev

Что еще должно быть настроено?

Другая часто используемая уловка с Django настройками, это изменить тип некоторых настроек с tuple на list. Для примера, INSTALLED_APPS изменить с:

INSTALLED_APPS = ( … )

INSTALLED_APPS = [ … ]

В foo/settings/base.py мы теперь можем проще добавлять и удалять приложения основываясь на конкретном файле настроек для текущего окружения. Для примера, возможно вам требуется модуль django-debug-toolbar установленным только в dev окружении.

Этот трюк также часто используется с настройками TEMPLATE_DIRS и MIDDLEWARE_CLASSES .

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

PREREQ_APPS = [ ‘ django . contrib . auth ’ , ‘ django . contrib . contenttypes ’ , … ‘ debug_toolbar ’ , ‘ imagekit ’ , ‘ haystack ’ , ] PROJECT_APPS = [ ‘ homepage ’ , ‘ users ’ , ‘ blog ’ , ] INSTALLED_APPS = PREREQ_APPS + PROJECT_APPS

Почему это часто используется? Во первых, это помогает лучше различать Django core компоненты, сторонние приложения и внутренние, специфичные для данного проекта. Тем не менее, PROJECT_APPS часто управляет списком специфичных пакетов, для вещей таких как: тестирование и покрытие кода тестами. Вы имеет список с вашими приложениями, поэтому можете легко и автоматизированно убедиться, что все тесты были запущены только для них, а не для каких-то посторонних модулей.

Исправляем зависимости

Большинство проектов содержат лишь один файл requirements.txt , который ставит зависимости примерно так:

pip install -r requirements.txt

Этого достаточно для маленьких проектов, но малоизвестная возможность requirements файлов это использование ключа -f для включения других файлов:

R base.txt pytest == 2.5.2 coverage == 3.7.1

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

Тестовые файлы

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

В итоге, вы уменьшите количество мердж конфликтов при работе в команде, что является положительной чертой. Маленькие файлы - ваши друзья.

Ссылки (URLs)

Для маленьких проектов заманчиво определять все ссылки в одном файле foo/urls.py для сохранения их в одном месте. Как бы то ни было, если ваша цель это ясность и реиспользование, вы должны определять ссылки в каждом приложении и загружать их в корневом файле. Вместо:

urlpatterns = patterns (‘’ , url (r ’ ^ $’ , HomePageView . as_view (), name = ‘ home ’ ), url (r ’ ^ blog / $’ , BlogList . as_view (), name = ‘ blog_list ’ ), url (r ’ ^ blog / (? P < pk > \d + ) / $’ , BlogDetail . as_view (), name = ‘ blog_detail ’ ), … url (r ’ ^ user / list / $’ , UserList . as_view (), name = ‘ user_list ’ ), url (r ’ ^ user / (? P < username > \w + ) / $’ , UserDetail . as_view (), name = ‘ user_detail ’ ), )

вы должны использовать:

urlpatterns = patterns (‘’ , url (r ’ ^ $’ , HomePageView . as_view (), name = ‘ home ’ ), url (r ’ ^ blog / ‘ , include (‘ blog . urls ’ )), url (r ’ ^ user / ‘ , include (‘ user . urls ’ )), )

Шаблоны и статические файлы

Использование templates/ и static/ директорий на каждое приложение дает способность к реиспользованию этого приложения в другом проекте как есть, без изменений.

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

Также, это дает нам возможность переопределить шаблоны на каждый проект базируясь на директории foo/templates/ . При добавлении шаблона templates/blog/detail.html мы перезаписываем или скрываем шаблон по умолчанию blog/templates/blog/detail.html .

Переиспользование Django приложений

Допустим, вы используете предлагаемую структуру проекта некоторое время, однажды, вы поймете, что ваш новый проект нуждается в блоге и один из ваших проектов прекрасно к этому подходит. Вы скопируете файлы в … НЕ ПРАВИЛЬНО! Теперь вы имеете две копии приложения. Исправления ошибок или новые функции в одном, будут вручную переноситься между проектами если предположить, что вы всегда помните про это.

Вместо этого, сделайте новый репозиторий для вашего блога и вставьте в него директорию foo/blog/ . И настройте, чтобы ваш существующий проект foo и новый проект, для установки блога через pip.

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

Дополнительные ресурсы

Наши друзья Дэнни и Аудрей из CartWheel Web напомнили нам про Cookie Cutter и специальный cookiecutter-django от Дэнни, мощная утилита для создания начального проекта, быстро и повторяемо.

Кроме того, если вы ищете все про Django уловки и рекомендации, вы не можете пройти мимо книги Two Scoops of Django: Best Practices For Django 1.6 которую мы рекомендуем всем нашим клиентам.

Обратная связь

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

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

Почему сборка пакетов так важна?

Помимо того, что это просто хороший тон, существуют еще три практические причины для поставки программного обеспечения в виде пакетов:

• простота использования;
• стабильность (при управлении версиями);
• распространение.

При выборе приложения простота его установки учитывается пользователями далеко не в последнюю очередь, поэтому следует максимально упростить этот процесс. Сборка пакетов позволяет сделать программное обеспечение более доступным и простым в установке. Если установка не сложная, значит, пользователям будет проще приступить к работе с вашим программным обеспечением. Повысить доступность своего пакета при его публикации в каталоге пакетов Python (Python Package Index — PyPI) можно посредством таких утилит как pip или easy_install . (См. для получения дополнительной информации по данным средствам.)

Кроме того, управление версиями пакетов позволяет пользователям «закрепить» свои проекты, использующее ваше программное обеспечение, за его определенной версией. Например, закрепление за Pinax версии 0.9a2.dev1017 будет выглядеть таким образом:

Pinax==0.9a2.dev1017

Это принудительно свяжет проект с Pinax версии 0.9a2.dev1017.

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

Наиболее популярным методом публикации пакетов на PyPI (или на вашем собственном дистрибутивном сервере) является создание дистрибутива исходного кода для его свободной загрузки. Дистрибутив исходного кода — это стандартный способ сборки кода вашего проекта в качестве распространяемого модуля. Можно также создавать бинарные дистрибутивы, но для целей открытого использования имеет смысл также распространять свой код. Создавая дистрибутивы исходного кода, вы облегчаете пользователям процесс нахождения программного обеспечения в сети Интернет с помощью автоматизированных средств, а также его загрузки и установки. Этот процесс помогает не только в разработке на локальных системах, но и в развертывании вашего программного обеспечения.

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

Анатомия файла setup.py

Одно из предназначений сценария setup.py — это исполнение сборки пакетов вашего программного обеспечения и загрузки его на дистрибутивные серверы. На различных популярных репозиториях Python вы можете найти сценарии setup.py различного содержания. В данной статье рассмотрены основные из них. См. раздел для получения дополнительной информации.

Файл setup.py может использоваться для различных целей, но ниже мы приводим вариант, который позволяет выполнить следующие команды:

python setup.py register python setup.py sdist upload

Первая команда, register , получает информацию, которую выдает функция setup() сценария setup.py, и создает запись в PyPI для вашего пакета. Она ничего не загружает, вместо этого она создает метаданные о вашем проекте с тем, чтобы впоследствии вы могли выгрузить и разместить там свои версии ПО. Следующие две команды связаны: sdist upload создает дистрибутив исходного кода, а затем выгружает его в PyPI. Тем не менее, существуют несколько необходимых условий, таких как настройка собственного конфигурационного файла.pypirc и собственно запись содержимого в файл setup.py.

Прежде всего, сконфигурируйте файл.pypirc. Он должен находиться в основном каталоге, который может быть разным в зависимости от используемой операционной системы. В операционных системах UNIX®, Linux® и Mac OS Xзайти в этот каталог можно, набрав cd ~/ . Содержимое файла должно включать ваши учетные данные PyPI, как показано в.

Листинг 1. Типовой файл.pypirc

index-servers = pypi username:xxxxxxxxxxxxx password:xxxxxxxxxxxxx

Далее переходите в PyPI и зарегистрируйтесь для создания учетной записи (не волнуйтесь — это бесплатно). Введите такое же имя пользователя и пароль, что и в файле.pypirc каталога PyPI, и убедитесь, что файл называется именно ~/.pypirc .

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

Листинг 2. Шаблон setup.py

PACKAGE = "" NAME = "" DESCRIPTION = "" AUTHOR = "" AUTHOR_EMAIL = "" URL = "" VERSION = __import__(PACKAGE).__version__ setup(name=NAME, version=VERSION, description=DESCRIPTION, long_description=read("README.rst"), author=AUTHOR, author_email=AUTHOR_EMAIL, license="BSD", url=URL, packages=find_packages(exclude=["tests.*", "tests"]), package_data=find_package_data(PACKAGE, only_in_packages=False), classifiers=[ "Development Status:: 3 - Alpha", "Environment:: Web Environment", "Intended Audience:: Developers", "License:: OSI Approved:: BSD License", "Operating System:: OS Independent", "Programming Language:: Python", "Framework:: Django", ], zip_safe=False,)

Во-первых, следует помнить, что этот шаблон подразумевает наличие в вашем проекте двух различных файлов. Первый используется для длинного описания (long_description). Он считывает содержимое файла README.rst, находящегося в той же директории, что и setup.py, и передает это содержимое как строку в параметр long_description . Этот файл заполняет целевую страницу в PyPI, поэтому желательно дать в нем краткое описание проекта и привести несколько примеров его использования. Второй файл — файл пакетов __init__.py . Мы не приводим здесь его развернутого описания, однако когда строка, которая определяет переменную VERSION, импортирует ваш пакет, Python требуется файл __init__.py, поэтому в данном модуле следует определить переменную с названием __version__ . Пока достаточно записать это строкой:

# __init__.py __version__ = "0.1"

Теперь взглянем на остальные исходные параметры.

• PACKAGE — это пакет Python в вашем проекте. Это папка верхнего уровня, содержащая модуль __init__.py, который должен находиться в той же директории, что и файл setup.py, например: /- |- README.rst |- setup.py |- dogs |- __init__.py |- catcher.py

  Итак, в данном случае вашим пакетом будет dogs .

• Параметр NAME обычно схож или совпадает с названием пакета PACKAGE, но вы можете задать любое имя в зависимости от ваших предпочтений. NAME — это параметр, по которому пользователи будут ссылаться на ваше программное обеспечение, имя, под которым ваше программное обеспечение будет отображаться в PyPI и, что более важно, под которым пользователи будут его устанавливать (например, pip install NAME).
• DESCRIPTION — краткое описание вашего проекта. Одного предложения будет достаточно.
• AUTHOR и AUTHOR_EMAIL — это соответственно: ваше имя и адрес электронной почты. Эта информация не обязательна, но указать свой адрес электронной почты для пользователей, которые пожелают обратиться к вам с вопросами по проекту, это правило хорошего тона.
• URL — это URL-адрес проекта. Этот параметр может быть как Web-сайтом проекта или репозиторием Github, так и любым другим URL-адресом. Эта информация также не обязательна.

Возможно, вы пожелаете указать лицензионные условия и классификаторы. Более детальная информация о создании файла setup.py приведена в документации по Python. (См. .)

Управление версиями

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

Стандарт по управлению версиями пакетов Python можно найти в PEP-386 (Предложение по развитию Python) (см. .) В нем прописаны правила практического характера. Даже если вы не читали, не поняли или даже не согласны с PEP, все же разумнее придерживаться установленных в нем правил, так как именно они все чаще применяются при создании разработчиками приложений Python.

Кроме того, управление версиями необходимо не только для разработки стабильных версий, загружаемых в PyPI, но также полезно для разработки версий с суффиксом devNN . Как правило, размещение разрабатываемых версий в PyPI не поощряется, но можно сделать их общедоступными посредством настройки собственного общедоступного (или закрытого) дистрибутивного сервера. В этом случае пользователи, которые желают воспользоваться последней версией, могут указать это в своем pip -файле requirements.txt. Ниже приведено несколько примеров управления версиями:

1.0.1 # 1.0.1 final release 1.0.2a # 1.0.2 Alpha (for Alpha, after Dev releases) 1.0.2a.dev5 # 1.0.2 Alpha, Dev release #5

Публикация

Пользователям не удастся отыскать и установить ваше программное обеспечение, если оно не будет опубликовано. Обычно пакеты публикуются в PyPI. Настроив свой конфигурационный файл.pypirc и передав команду upload в setup.py, вы передадите пакет в PyPI. Как правило, эта операция производится совместно с созданием дистрибутива исходного кода:

python setup.py sdist upload

В случае использования собственного дистрибутивного сервера, добавьте раздел для авторизации в своем файле.pypirc для этого нового местоположения и укажите ссылку на него при выгрузке:

python setup.py sdist upload -r mydist

Настройка собственного дистрибутивного сервера

Главной причиной использования собственного дистрибутивного сервера для проектов с открытым исходным кодом является потребность в публикации разрабатываемых версий, так как PyPI может содержать только стабильные приложения. Например, возможно вы захотите:

pip install MyPackage

Установить последнюю стабильную версию в PyPI. Но если вы позднее добавите разрабатываемые версии, то эта команда остановит выполнение и установит последнюю версию, т. е. разрабатываемую версию. Как правило, полезно всегда закреплять проекты за определенной версией, но это делают не все пользователи. Поэтому следует убедиться в том, что, если номер версии не указан, по умолчанию возвращается последняя стабильная версия.

Одним из способов убить одним выстрелом двух зайцев (предоставлять только стабильные версии для использования pip по умолчанию и обеспечить пользователям возможность устанавливать пакеты разрабатываемых версий) является создание собственного дистрибутивного сервера. Проект Pinax применяет эту технологию для всех своих разрабатываемых версий на сайте http://dist.pinaxproject.com. (См. .)

Дистрибутивный сервер представляет собой каталог, работающий по протоколу HTTP и предоставляющий доступ к файлам на вашем сервере. Он должен иметь следующую файловую структуру:

/index-name/package-name/package-name-version.tar.gz

В дальнейшем при желании сервер можно сделать закрытым путем конфигурирования Basic-Auth на своем Web-сервере. Вы также можете добавить некоторые другие средства для выгрузки дистрибутивов исходного кода. Для этого необходимо добавить код управления выгрузкой, разобрать название файла и создать пути по каталогу, которые бы соответствовали приведенной выше схеме. Такая структура принята для проектов Pinax с использованием нескольких репозиториев.

pip и virtualenv

Хотя данная статья посвящена в основном сборке пакетов, дабы отдать должное тем преимуществам, которые сборка пакетов и управление версиями дают вашим пользователям, этот раздел описывает использование пакетов.

Инструмент pip можно установить напрямую, однако я рекомендую использовать его в рамках функциональности virtualenv . (См. .) Я также советую прибегать к virtualenv во всех случаях, когда вы имеете дело с Python, так как окружение Python при этом остается незагроможденным. Подобно тому, как виртуальная машина позволяет запускать несколько операционных систем одновременно, virtualenv позволяет запускать несколько окружений Python одновременно. Я ничего не устанавливаю в своей системе Python, а просто создаю новое виртуальное окружение для каждого нового проекта или утилиты, над которыми работаю.

Теперь, когда инструмент virtualenv установлен, можно и немного поиграть:

$ mkvirtualenv -no-site-packages testing $ pip install Pinax $ pip freeze|grep Pinax $ pip uninstall Pinax $ pip install -extra-index-url=http://dist.pinaxproject.com/fresh-start/ Pinax==0.9a2.dev1017 $ pip freeze|grep Pinax

Обратите внимание, что первая установка pip загружается и устанавливается с PyPI. Команда pip freeze выводит все версии пакетов, установленных в текущем virtualenv . Команда pip uninstall делает именно то, о чем говорит ее название: удаляет себя из virtualenv . Затем мы устанавливаем разрабатываемую версию из репозитория перезагрузки по адресу http://dist.pinaxproject.com, чтобы получить разрабатываемую версию Pinax 0.9a2.dev1017.

Переходить на Web-сайт, загружать tar-архивы и создавать коды символических ссылок (symlink) на каталог site-packages не требуется. (Раньше я так и делал, и это вызывало много проблем.) Все это ваши пользователи получают благодаря хорошей сборке пакетов, публикации и управлению версиями созданного проекта.

Заключение

Надеюсь, материала, изложенного в данной статье, достаточно для того, чтобы вы смогли приступить к работе. В разделе приведены ссылки на документацию, которая может помочь вам глубже разобраться в упомянутых вопросах. Если у вас возникнут какие-либо вопросы, заходите на Freenode и ищите меня в таких разделах чата как #pinax и #django-social (по псевдониму "paltman") или в Twitter (@paltman).