Distribuindo módulos Python
***************************

E-mail:
   distutils-sig@python.org

Como um projeto popular de desenvolvimento de código aberto, Python
tem uma comunidade de apoio ativa de colaboradores e usuários, que
também fazem o seu software disponível para outros desenvolvedores de
Python para usar sob os termos da licença de código aberto.

Isso permite aos usuários Python compartilhar e colaborar
efetivamente, se beneficiando das soluções que outros já tenham criado
para os problemas mais comuns (em alguns casos até mesmo os raros),
bem como potencialmente contribuindo com suas próprias soluções para o
conjunto de soluções comuns.

Este guia cobre a parte de distribuição do processo. Para um guia de
instalação de outros projetos Python, consulte installation guide.

Nota:

  Para corporações e outros usuários institucionais, esteja ciente que
  muitas organizações têm suas próprias políticas em relação ao uso e
  contribuição para o software de código aberto. Por favor, leve em
  conta essas políticas ao usar as ferramentas de distribuição e
  instalação fornecidas com o Python.


Termos chave
============

* Python Packaging Index é um repositório público de pacotes
  licenciados como código aberto e disponíveis para uso de outros
  usuários Python

* o Python Packaging Authority é o grupo de desenvolvedores e autores
  de documentação responsáveis pela manutenção e evolução das
  ferramentas de empacotamento padrão e pelos padrões de metadados e
  formato de arquivo associados. Eles mantêm uma variedade de
  ferramentas, documentação e rastreadores de problemas no GitHub e
  Bitbucket.

* "distutils" é o primeiro sistema de construção e distribuição
  adicionado na biblioteca padrão do Python, em 1998. Embora o uso
  direto do "distutils" esteja sendo eliminado, ele estabelece as
  bases para a infraestrutura atual de empacotamento e distribuição, e
  não somente permanece como parte da biblioteca padrão, mas seu nome
  continua sendo usado de outras maneiras (como o nome da lista de
  e-mail usada para coordenar o desenvolvimento dos padrões de
  empacotamento Python).

* setuptools é um substituto (em grande parte) para "distutils",
  publicado pela primeira vez em 2004. Sua adição mais notável sobre
  as ferramentas "distutils" originais foi a capacidade de declarar
  dependências em outros pacotes. Atualmente é recomendado como uma
  alternativa, mais regularmente atualizada, para "distutils", que
  oferece suporte consistente para padrões de empacotamento mais
  recentes, em uma ampla gama de versões do Python.

* wheel (nesse contexto) é um projeto que adiciona o comando
  "bdist_wheel" ao "distutils"/setuptools. Isso produz um formato de
  pacote binário, portável entre várias plataformas (chamado "wheels"
  ou "wheel files" e definido no **PEP 427**), permitindo que
  bibliotecas Python, mesmo aquelas incluindo extensões binárias,
  sejam instaladas em um sistema, sem precisarem ser construídas
  localmente.


Licenciamento de código aberto e colaboração
============================================

Na maior parte do mundo, o software é automaticamente coberto por
direitos autorais. Isso significa que outros desenvolvedores precisam
de permissão explícita para copiar, usar, modificar e redistribuir o
software.

O licenciamento de código aberto é uma forma de conceder
explicitamente tal permissão, de maneira relativamente consistente,
permitindo aos desenvolvedores compartilhar e colaborar de forma
eficiente, criando soluções comuns para vários problemas disponíveis
gratuitamente. Isso permite que os desenvolvedores dediquem mais tempo
focados nos problemas que são relativamente exclusivos para sua
situação específica.

As ferramentas de distribuição fornecidas com o Python são projetadas
para tornar razoavelmente simples, para os desenvolvedores, fazerem
suas próprias contribuições, de volta para esse conjunto comum de
software, se optarem por fazê-lo.

As mesmas ferramentas de distribuição também podem ser usadas para
distribuir software dentro de uma organização, independentemente de
esse software ser publicado como software de código aberto ou não.


Instalando as ferramentas
=========================

A biblioteca padrão não inclui ferramentas de construção que suportem
padrões de empacotamento modernos do Python, pois a equipe de
desenvolvimento principal achou que é importante ter ferramentas
padrão que funcionem consistentemente, mesmo em versões mais antigas
do Python.

As ferramentas de construção e distribuição, recomendadas atualmente,
podem ser instaladas chamando o módulo "pip" na linha de comando:

   python -m pip install setuptools wheel twine

Nota:

  Para usuários POSIX (incluindo usuários Mac OS X e Linux), essas
  instruções assumem o uso de um *virtual environment*.Para usuários
  Windows, essas instruções assumem que a opção de ajustar a variável
  de ambiente do sistema, PATH, foi selecionado durante a instalação
  do Python.

O "Python Packaging User Guide" inclui mais detalhes sobre currently
recommended tools.


Lendo o "Python Packaging User Guide"
=====================================

O "Python Packaging User Guide" abrange as várias etapas e elementos-
chave envolvidos na criação e publicação de um projeto:

* Estrutura do projeto

* Compilando e empacotando o projeto

* Enviando o projeto para o Python Packaging Index

* O arquivo .pypirc


Como eu...?
===========

Estas são respostas rápidas ou links para algumas tarefas comuns.


... escolho um nome para meu projeto?
-------------------------------------

Não é um tema fácil, mas aqui estão algumas dicas:

* verifique o "Python Packaging Index" para ver se o nome já está em
  uso

* verifique sites de hospedagem populares como GitHub, Bitbucket etc.
  para ver se já existe um projeto com esse nome

* verifique o que surge, em uma pesquisa na Web, para o nome que você
  está considerando

* evite palavras particularmente comuns, especialmente aquelas com
  vários significados, pois elas podem dificultar que os usuários
  encontrem o seu software ao procurá-lo


... crio e distribuo extensões binárias?
----------------------------------------

Este é realmente um tema bastante complexo, com uma variedade de
alternativas disponíveis, dependendo exatamente do que você pretende
alcançar. Veja "Python Packaging User Guide" para mais informação e
recomendações.

Ver também: Python Packaging User Guide: Binary Extensions
