Publique seu pacote Python que está no PyPI no conda-forge

Nas lições anteriores, você aprendeu:

1. Como criar a versão mais básica de um pacote Python. Isso envolveu tornar seu código instalável.

2. Como publicar seu pacote Python no PyPI

3. Como adicionar arquivos README e LICENSE ao seu pacote

4. Como configurar seu arquivo pyproject.toml com toda a metadata exigida pelo PyPI e também metadata que ajudará usuários a encontrar seu pacote.

Se você passou por todas as lições acima, agora está pronto para publicar seu pacote no conda-forge.

IMPORTANTE: Por favor, não pratique publicar seu pacote no conda-forge. Você só deve publicar no conda-forge quando tiver um pacote no pypi.org que planeja manter.

Objetivos de Aprendizagem

Nesta lição você aprenderá como:

• Criar uma recipe YAML do conda-forge para seu pacote usando Grayskull

• Enviar a recipe (arquivo YAML) para o repositório staged recipes do conda-forge como pull request

• Manter seu pacote no conda-forge criando novos releases para seu pacote no PyPI

Depois que seu pacote estiver no PyPI, você pode publicá-lo facilmente no conda-forge usando a ferramenta grayskull. Você não precisa fazer build do pacote especificamente para conda; o conda-forge irá construir a partir do arquivo distribuição fonte (sdist) do PyPI.

Depois que você publicou ambas as distribuições do pacote (a distribuição fonte (sdist) e a Wheel (.whl)) no PyPI, pode publicar no conda-forge. O conda-forge exige uma source distribution no PyPI para fazer build do seu pacote no conda-forge. Você não precisa refazer o build do seu pacote para publicar no conda-forge.

O que é conda-forge?

conda é uma ferramenta open source de gerenciamento de pacotes e ambientes que pode ser usada para instalar ferramentas de diferentes channels no Anaconda.org.

Você pode pensar em um channel como um local específico onde um grupo de pacotes é armazenado e pode ser instalado usando um comando como conda install packagename. No caso de conda channels, alguns desses channels, como o channel defaults, são gerenciados pela Anaconda (a empresa). Somente a Anaconda decide quais pacotes estão disponíveis no channel defaults. No entanto, os channels conda-forge (e bioconda)são gerenciados pela comunidade. Qualquer pessoa pode submeter um pacote a esses channels, porém ele precisa passar por uma revisão técnica no repositório staged-recipes no GitHub para ser publicado.

Saiba mais sobre conda channels aqui.

Conda channels representam vários repositórios de onde você pode instalar pacotes. Como o conda-forge é mantido pela comunidade, qualquer pessoa pode submeter uma recipe lá. O PyPI também é um repositório mantido pela comunidade. Qualquer pessoa pode submeter um pacote ao PyPI e ao test PyPI. Diferentemente do conda-forge, não há verificações manuais de pacotes submetidos ao PyPI.

Por que publicar no conda-forge

Existem muitos usuários, especialmente no ecossistema científico Python, que usam conda como seu gerenciador de pacotes / ferramenta deambientes principal. Assim, ter pacotes disponíveis para esses usuários no channel conda-forge é útil. Em alguns casos, pacotes no conda-forge podem minimizar conflitos de dependências que podem ocorrer ao misturar instalações usando pip e conda. Isso é particularmente importante para o ecossistema espacial.

Como funciona a publicação no conda-forge

Depois de fazer o build e publicar seu pacote no PyPI, você tem tudo o que precisa para publicar no conda-forge. Não há etapa adicional de build necessária para publicar no conda-forge.

O conda-forge fará o build do seu pacote a partir da source distribution que você publicou no PyPI na lição anterior, usando a recipe que você criará abaixo.

Etapas de publicação no conda-forge

As etapas para publicar no conda-forge começam com a publicação do seu pacote Python no PyPI. Depois de publicar no PyPI, você pode criar um arquivo yaml de recipe que pode ser submetido ao repositório staged recipes do conda-forge para revisão. Depois que essa recipe for aceita, seu pacote terá seu próprio repositório (conhecido como feedstock) no conda-forge.

As etapas para publicar no conda-forge são:

1. Publique os arquivos de distribuição do seu pacote Python (sdist e wheel) no PyPI

2. Crie uma recipe conda-forge, que é um arquivo yaml com instruções sobre como fazer o build do seu pacote no conda-forge, usando o pacote grayskull[1].

3. Submeta a recipe (arquivo yaml) ao repositório staged recipes do conda-forge como um pull request para revisão. Clique aqui para ver um exemplo de submissão do pyOpenSci.

4. Depois que alguém da equipe conda-forge revisar seu pull request, você pode precisar fazer algumas alterações. Eventualmente o pull request será aprovado e merged.

Depois que sua recipe for aceita e merged no conda-forge, os usuários poderão instalar seu pacote usando:

conda install -c conda-forge your-package

Você cria a recipe apenas uma vez. Depois que a recipe for aceita e merged, você só precisa manter o repositório.

Mantendo um pacote conda-forge

Depois que seu pacote estiver no conda-forge, o repositório acompanhará a atividade de release no repositório PyPI do pacote. Sempre que você fizer um novo release no PyPI com uma nova source distribution, o conda-forge fará o build e atualizará seu repositório conda-forge (também conhecido como feedstock).

Quando a atualização for processada, o amigável bot conda-forge criará um novo pull request com uma recipe de distribuição atualizada no seu feedstock.

Você pode revisar esse pull request e depois fazer merge assim que todos os testes de integração contínua passarem.

Como publicar seu pacote no conda-forge

É hora de adicionar seu pacote ao channel conda-forge. Lembre-se de que seu pacote precisa estar no PyPI antes que as etapas abaixo funcionem. E lembre-se também de que a equipe que gerencia o conda-forge é formada por voluntários.

• Certifique-se de que seu pacote está no PyPI.org (não no test.pypi.org) antes de tentar publicar no conda-forge.

Importante

Submeta seu pacote ao conda-forge somente se você pretende mantê-lo ao longo do tempo.

Nota: este é um tutorial destinado a ajudá-lo a colocar seu pacote no conda-forge. A documentação oficial do conda para esse processo está aqui.

Etapa 1: Instalar grayskull

Primeiro, instale o grayskull. Você pode instalá-lo usando pip:

> python -m pip install grayskull

ou conda

> conda install -c conda-forge grayskull

Para executar este comando, use o mesmo shell / terminal que você usou para executar comandos hatch nos tutoriais anteriores.

Nota

Você também pode instalar o grayskull usando pipx[2]. pipx é uma ferramenta que permite instalar ferramentas comumente usadas que você pode querer ter disponíveis em vários ambientes Python, em vez de instalar o pacote em cada ambiente Python que você cria.

Etapa 2: Fazer fork e clonar o repositório staged-recipes do conda-forge

• Em seguida, abra seu shell e cd para um local onde você quer clonar o repositório conda-forge/staged-recipes.

• faça fork e clone o repositório conda-forge/staged-recipes no GitHub.

• Crie um novo branch no seu fork em vez de submeter a partir do branch main do seu fork. Sugerimos nomear o branch com o nome do seu pacote.

git checkout -b your-package-name

• No bash, cd para a pasta staged-recipes/recipes

staged-recipes/recipes (☊ pyospackage)
# Clone the repository
➜ git clone git@github.com:conda-forge/staged-recipes.git

Em seguida, crie um novo branch no repositório clonado conda-forge/staged-recipes. Você pode querer que esse branch tenha o mesmo nome do seu pacote.

# Create a new branch called pyospackage
➜ git checkout -b pyospackage
➜ cd staged-recipes/recipes
➜ git branch
  main
* pyospackage

Etapa 3: Criar sua recipe conda-forge

• Em seguida, navegue até o diretório recipes

Se você executar ls aqui, notará que há um diretório de exemplo com uma recipe de exemplo para você consultar.

staged-recipes (☊ pyospackage) via 🐍 pyenv
➜ cd recipes

staged-recipes/recipes (☊ pyospackage)
➜ ls
example

• Em seguida, execute grayskull pypi your-package-name para gerar uma recipe.

➜ grayskull pypi pyospackage

#### Initializing recipe for pyospackage (pypi) ####

Recovering metadata from pypi...
Starting the download of the sdist package pyospackage
pyospackage 100% Time:  0:00:00   1.2 MiB/s|###########################|
Checking for pyproject.toml
pyproject.toml found in /var/folders/r8/3vljpqb55psbgb1ghc2qsn700000gn/T/grayskull-pyospackage-du0sf_a4/pyospackage-0.0.1/pyproject.toml
Recovering information from setup.py
Executing injected distutils...
Checking >> -- 100% |#                          |[Elapsed Time: 0:00:00]
Matching license file with database from Grayskull...
Match percentage of the license is 97%. Low match percentage could mean that the license was modified.
License type: MIT
License file: ['LICENSE']
Build requirements:
  <none>
Host requirements:
  - python
  - hatchling
  - pip
Run requirements:
  - python

RED: Missing packages
GREEN: Packages available on conda-forge

Maintainers:
   - lwasser

#### Recipe generated on /your/file/package/here/pyosPackage for pyospackage ####

# You should see a new directory created by grayskull after this run is completed.
staged-recipes/recipes (☊ pyospackage)
➜ ls
example         pyospackage

Dica

• O Grayskull buscará metadata sobre seu pacote no PyPI. Ele não usa sua instalação local do pacote.

• Uma conexão com a internet é necessária para executar a etapa grayskull pypi your-package-name.

Quando você executar grayskull, ele obterá a distribuição mais recente do seu pacote no PyPI e usará isso para criar uma nova recipe.

A recipe será salva em um diretório nomeado com o nome do seu pacote, onde quer que você execute o comando.

recipes/packagename/meta.yaml

Na parte inferior da saída do grayskull, ele também informará onde salvou o arquivo de recipe.

Abra o arquivo meta.yaml. O arquivo meta.yaml final que o grayskull cria deve se parecer com o exemplo abaixo:

{% set name = "pyospackage" %}
{% set version = "0.1.8" %}

package:
  name: {{ name|lower }}
  version: {{ version }}

source:
  url: https://pypi.org/packages/source/{{ name[0] }}/{{ name }}/{{ name.replace('-', '_') }}-{{ version }}.tar.gz
  sha256: 43ec82da3a10752a5dbf2f0ef742e357803a3ddb400005f87e86534685bfb8a7

build:
  noarch: python
  script: {{ PYTHON }} -m pip install . -vv --no-deps --no-build-isolation
  number: 0

requirements:
  host:
    - python
    - hatchling
    - pip
  run:
    - python

test:
  imports:
    - pyospackage
  commands:
    - pip check
  requires:
    - pip

about:
  summary: A package that adds numbers together
  dev_url: https://github.com/pyopensci/pyospackage
  license: BSD-3-Clause
  license_file: LICENSE

extra:
  recipe-maintainers:
    - lwasser

Etapa 3b: Correção de bug — adicionar uma home url à seção about

Atualmente há um pequeno bug no Grayskull em que ele não preenche o elemento home: da recipe. Se você não incluir isso, receberá uma mensagem de errodoamigávelbotlinter do conda-forge.

Hi! This is the friendly automated conda-forge-linting service.

I wanted to let you know that I linted all conda-recipes in your PR (recipes/pyospackage) and found some lint.

Here's what I've got...

For recipes/pyospackage:

The home item is expected in the about section.

• para corrigir isso, abra seu arquivo meta.yaml no seu editor de texto favorito.

• e adicione um elemento home: à seção about

A seção about ficará assim depois que você criar sua recipe.

about:
  summary: A package that adds numbers together
  dev_url: https://github.com/pyopensci/pyospackage
  license: BSD-3-Clause
  license_file: LICENSE

Abaixo você adiciona um elemento home:. Se você tiver uma home page / website do projeto, pode usar essa url. Caso contrário, você também pode usar sua landing page no PyPI.

about:
  home: https://pypi.org/project/pyospackage/
  summary: A package that adds numbers together
  dev_url: https://github.com/pyopensci/pyospackage
  license: BSD-3-Clause
  license_file: LICENSE

Etapa 4: testes para conda-forge

Em seguida, dê uma olhada na seção tests do seu arquivo meta.yaml. No mínimo, você deve importar seu pacote ou os principais modules associados ao seu pacote e executar pip check.

pip check garantirá que seu pacote seja instalado corretamente com todas as dependências adequadas.

test:
  imports:
    - pyospackage # Test importing the package into a python environment
  commands:
    - pip check # check the package
  requires:
    - pip

Se você tiver testes mais avançados que deseja executar, pode adicioná-los aqui. No entanto, você também pode simplesmente deixar a seção tests como está.

Etapa 4: Submeter um pull request ao repositório staged-recipes

Depois de concluir tudo acima, você está pronto para abrir um pull request no repositório conda-forge/staged-recipes.

1. Submeta um pull request a partir do fork/branch do repositório staged-recipes.

2. Lembre-se de que os maintainers do conda-forge são voluntários. Seja paciente aguardando uma resposta e colaborativo na comunicação com eles.

Ajuda com checklist do conda-forge

Checklist de pull request do Staged-recipes conda-forge

Quando você submete seu pacote ao conda-forge, o template de pull request inclui uma lista de verificações que você deve garantir ter coberto.

Abaixo detalhamos cada elemento dessa lista.

Dicas do checklist do template de pull request

-[x] O título deste PR é significativo: por exemplo, «Adding my_nifty_package», não «updated meta.yaml».

Tradução: Certifique-se de que o título do seu pull request seja específico. Sugerimos algo como: Add recipe for <your package name>

-[x] O arquivo LICENSE está incluído no pacote (veja aquiumexemplo).

Tradução: Você deve ter um arquivo LICENSE incluído na source distribution do seu pacote. Se você seguiu os tutoriais do pyOpenSci, já tem um arquivo LICENSE e provavelmente está usando a licença MIT. Quando você executar hatch build, ele incluirá esse arquivo na source distribution (que é o arquivo tar.gz) que o conda-forge usará para fazer o build do seu pacote.

• [x] A source é de uma fonte oficial.

Tradução: Se seu pacote está no PyPI, como você aprendeu na lição anterior sobre publicar seu pacote Python, você está em boa forma. O conda-forge prefere que sua distribuição seja publicada em um repositório conhecido.

-[x] O pacote não inclui (vendor) outros pacotes. (Se um pacote usa o source de outro pacote, eles devem ser pacotes separados ou as licenças de todos os pacotes precisam ser incluídas).

Tradução: Se a base de código do seu pacote é sua e tudo compartilha a mesma LICENSE, você está em boa forma. Se você tem código retirado de outros pacotes, pode precisar declarar isso e incluir licenças para esse código se for diferente. Se você seguiu estes tutoriais, não tem nenhum código vendored.

-[x] Se bibliotecas estáticas forem linkadas, a licença da biblioteca estática está incluída no pacote.

-[x] O pacote não distribui bibliotecas estáticas. Se bibliotecas estáticas forem necessárias, siga o CFEP-18.

Tradução: Uma biblioteca estática refere-se a uma cópia de um pacote incorporada ao seu pacote. Se seu pacote é um pacote puro Python, você pode marcar que seu pacote não distribui bibliotecas estáticas, pois isso não se aplica a você.

Os tutoriais do pyOpenSci são todos pure Python e, como tal, não usam bibliotecas estáticas em formato linkado ou shipped (incluído na distribuição do pacote).

Se seu pacote tem um build mais complexo que inclui links para extensões escritas em outras linguagens, como C++, certifique-se de incluir as licenças adequadas para essas extensões no seu metadata.

Nota

Se você quiser saber mais sobre bibliotecas estáticas, esta visão geralpodeajudar.

-[ ] O build number é 0.

Tradução: O numero da sua build recipe fica logo abaixo da localização da source distribution do seu pacote. number: 0 é o que você deve ver nessa seção da sua recipe.

source:
 url: https://pypi.org/packages/source/{{ name[0] }}/{{ name }}/{{ name.replace('-', '_') }}-{{ version }}.tar.gz
 sha256: 01e31f5521973710d0d91b15a94491d4f8f8f54566322110098c0f2381dd09ab

build:
 noarch: python
 script: {{ PYTHON }} -m pip install . -vv --no-deps --no-build-isolation
 number: 0

• [x] Um tarball (url) em vez de um repo (por exemplo, git_url) é usado na sua recipe (veja aqui mais detalhes).

Tradução: Aqui o conda quer que você forneça um link para a source distribution no PyPI em vez de um link para a distribuição do seu repositório GitHub. Observe acima na seção Source da sua recipe que há uma seção url: que fornece uma url do PyPI terminando em tar.gz. Esse é um link para sua source distribution que o conda-forge usará.

url: https://pypi.org/packages/source/{{ name[0] }}/{{ name }}/{{ name.replace('-', '_') }}-{{ version }}.tar.gz

• [x] Usuários do GitHub listados na seção maintainer postaram um comentário confirmando que estão dispostos a ser listados lá.

Tradução Depois de submeter sua recipe, certifique-se de que todos os maintainers listados na sua recipe respondam confirmando que concordam em ser listados como maintainer da versão conda-forge do seu package.

• [x] Em caso de problemas, consulte nossa documentação da base de conhecimentoantesdemencionarumaequipe.

Tradução A equipe conda são voluntários que dedicam seu tempo para apoiar nossa comunidade. Tente resolver por conta própria antes de marcar um deles para pedir ajuda.

É por isso também que não sugerimos publicar no conda-forge como um exercício de prática.

Depois de criar seu pull request, um conjunto de ações de CI será executado que faz o build e testa o build do seu pacote. Um maintainer do conda-forge trabalhará com você para deixar sua recipe em boa forma e fazer merge.

Aguarde até que todas as etapas de CI do seu pull request tenham sido executadas. Nesse ponto, seu pull request está pronto para revisão por um maintainer do conda-forge.

Em alguns casos, fazer com que todas as verificações passem com sucesso no CI pode exigir um pouco de trabalho. Se você estiver com dificuldade para fazer sua recipe buildar corretamente, pode mencionara equipe de maintainers do conda-forge para pedir ajuda.

Seja paciente e aguarde a resposta deles.

staged recipes do conda-forge e falhas de CI

Se seu pacote é um pure pacote Python que pode ser instalado em qualquer tipo de computador (Windows, mac, linux) e não tem requisitosde arquitetura (conhecido como noarch: Python ou sem requisitos de arquitetura), a equipe conda-forge exige apenas que os testes de CI Linux passem.

Então, se os testes para Windows e MAC OS falharem, isso é esperado. Nesse caso, não se preocupe com testes falhando; a equipe de maintainers pode ajudá-lo a publicar seu pacote.

Depois de submeter sua recipe, você pode aguardar o build de CI passar. Se não estiver passando e você não souber por quê, um maintainer do conda-forge provavelmente pode ajudá-lo a descobrir.

Depois que sua recipe for construida e merged, a equipe conda criará um novo repositório de pacote para você, semelhante a este do pacote GemGIS.

Parabéns — você adicionou seu pacote ao conda-forge.

A última parte deste processo é manter o repositório. Cobrimos isso a seguir.

Mantendo seu feedstock conda-forge

Toda vez que você criar um novo release no PyPI, os bots do conda-forge reconhecerão o release e farão rebuild da versão recém-lançada do seu pacote. Esse processo pode levar um ou dois dias para concluir, então seja paciente.

Quando o build do conda-forge estiver concluído, todos os maintainers do seu feedstock conda-forge receberão uma menção no GitHub informando que um novo pull request foi aberto.

Revise o pull request. Se todos os testes estiverem passando, você pode fazer merge. Um pouco depois de fazer merge do seu pull request, o release conda-forge estará disponível para os usuários instalarem:

conda install -c conda-forge yourpackage

Encerramento

Se você percorreu toda esta série de tutoriais, agora você:

1. Entende o que é um pacote Python

2. Sabe como tornar seu código instalável em ambientes Python

3. Sabe como criar um arquivo pyproject.toml, um arquivo README, um LICENSE e um code of conduct.

4. Sabe como publicar seu pacote no PyPI e

5. Sabe como publicar seu pacote no conda-forge

Os itens acima são as etapas básicas que você precisa seguir para criar e publicar um pacote Python. Em uma futura série de tutoriais, cobriremos o básico de manter seu pacote.

Notas de rodapé

[1]

Post do blog Grayskull

[2]

Documentação do Pipx