Transformando um projeto Python pessoal em uma biblioteca liberável

Sou acadêmico, e não programador, e tenho muitos anos de experiência escrevendo programas em Python para meu próprio uso, para apoiar minha pesquisa. Meu projeto mais recente provavelmente será útil para muitos outros, além de mim, e estou pensando em lançá-lo como uma biblioteca Python de código aberto.

No entanto, parece haver alguns obstáculos a atravessar entre um projeto pessoal em funcionamento e uma biblioteca que pode ser instalada e usada sem dor por outras pessoas. Esta pergunta é sobre os primeiros passos que devo tomar para começar a trabalhar em direção a um lançamento público.

Atualmente, eu tenho um único repositório git que contém meu código que usa a biblioteca e a própria biblioteca, e eu uso o git como um botão de desfazer de emergência, caso algo quebre. Tudo isso funciona bem para um único usuário, mas obviamente não é apropriado se eu quiser liberá-lo. Onde eu quero terminar é que minha biblioteca está em um repositório separado e pode ser instalada por outras pessoas usando pipe possui uma API estável.

Aprender a usar o setuptools etc. provavelmente não é tão difícil assim que pretendo publicá-lo - meu problema é saber como devo trabalhar para chegar a esse ponto.

Então, minha pergunta é: quais são os primeiros passos que você deve tomar para começar a preparar um projeto de biblioteca Python para consumo público? Como devo reorganizar minha estrutura de diretórios, repositório git etc. para começar a trabalhar para o lançamento público da biblioteca?

De maneira mais geral, seria muito útil se houver recursos que sejam úteis ao tentar fazer isso pela primeira vez. Indicadores sobre as melhores práticas e erros a serem evitados etc. também seriam muito úteis.

Alguns esclarecimentos: as respostas atuais estão tratando de uma pergunta do tipo "como posso tornar minha biblioteca Python uma boa para outras pessoas usarem?" Isso é útil, mas é diferente da pergunta que pretendia fazer.

Atualmente, estou no início de uma longa jornada para lançar meu projeto. O núcleo da minha implementação funciona (e funciona muito bem), mas estou me sentindo sobrecarregado com a quantidade de trabalho que tenho pela frente e estou procurando orientações sobre como navegar no processo. Por exemplo:

• Atualmente, o código da minha biblioteca está acoplado ao meu próprio código específico de domínio que o utiliza. Ele vive em uma subpasta e compartilha o mesmo repositório git. Eventualmente, ele precisará ser transformado em uma biblioteca independente e colocado em seu próprio repositório, mas continuo procrastinando isso porque não sei como fazê-lo. (Nem como instalar uma biblioteca no 'modo de desenvolvimento' para que eu ainda possa editá-la, nem como manter os dois repositórios git em sincronia.)

• Minhas doutrinas são concisas, porque sei que eventualmente terei que usar o Sphinx ou alguma outra ferramenta. Mas essas ferramentas parecem não ser fáceis de aprender, então isso se torna um subprojeto importante e eu continuo adiando.

• Em algum momento, preciso aprender a usar o setuptools ou alguma outra ferramenta para empacotá-lo e rastrear as dependências, que são bastante complexas. Não tenho certeza se preciso fazer isso agora ou não, e a documentação é um labirinto absoluto para um novo usuário, por isso continuo decidindo fazê-lo mais tarde.

• Eu nunca tive que fazer testes sistemáticos, mas definitivamente o farei para este projeto, então tenho que (i) aprender o suficiente sobre testes para saber qual metodologia é adequada para o meu projeto; (ii) aprender quais ferramentas estão disponíveis para minha metodologia escolhida; (iii) aprender a usar minha ferramenta escolhida; (iv) implementar conjuntos de testes etc. para o meu projeto. Este é um projeto em si.

• Pode haver outras coisas que eu tenho que fazer também. Por exemplo, jonrsharpe postou um link útil que menciona git-flow, tox, TravisCI, virtualenv e CookieCutter, nenhum dos quais eu tinha ouvido falar antes. (O post é de 2013, então eu também tenho que trabalhar para descobrir quanto ainda está atual.)

Quando você junta tudo isso, é uma enorme quantidade de trabalho, mas tenho certeza de que posso fazer tudo se continuar insistindo e não tiver pressa. Meu problema é saber como dividi-lo em etapas gerenciáveis ​​que podem ser executadas uma de cada vez.

Em outras palavras, estou perguntando quais são as medidas concretas mais importantes que posso tomar agora, para alcançar um produto liberável eventualmente. Se eu tiver um fim de semana gratuito, em quais dessas coisas devo me concentrar? Qual (se houver) pode ser feito isoladamente dos outros, para que eu possa pelo menos dar um passo sem precisar fazer a coisa toda? Qual é a maneira mais eficiente de aprender essas coisas para que eu ainda tenha tempo para me concentrar no próprio projeto? (Tendo em mente que tudo isso é essencialmente um projeto de hobby, não é meu trabalho.) Existe algo que eu realmente não preciso fazer , economizando uma quantidade enorme de tempo e esforço?

Todas as respostas são muito apreciadas, mas gostaria especialmente de receber respostas que se concentrem nesses aspectos de gerenciamento de projetos, com referência específica ao desenvolvimento moderno do Python.

Adicionar um setup.py, enquanto necessário, não é a etapa mais importante se você deseja que sua biblioteca seja usada. Mais importante é adicionar documentação e anunciar sua biblioteca. Como o segundo ponto depende fortemente da biblioteca, deixe-me focar no aspecto da documentação.

1. Você sabe tudo sobre sua biblioteca. E isso é problemático. Você já sabe como instalar e usá-lo; muitas coisas podem parecer intuitivas ou claramente óbvias para você. Infelizmente, as mesmas coisas podem não ser óbvias nem intuitivas para os usuários. Tente olhar para a sua biblioteca como se não soubesse nada sobre ela e, mais importante, peça a outras pessoas que a usem e tente identificar todas as dificuldades que tiveram.

2. Explique, em inglês simples, sobre o que é sua biblioteca. Muitas bibliotecas assumem que todo mundo sabe sobre elas. Quando esse não é o caso, pode ser difícil entender qual é o objetivo da biblioteca.

3. Escreva documentação técnica detalhada, mas também não se esqueça de pequenos trechos de código que mostram como executar algumas das tarefas com sua biblioteca. A maioria dos desenvolvedores tem pressa e, se precisar gastar horas tentando entender como fazer uma coisa básica, pode tender a mudar para outras bibliotecas.

4. Inclua suas informações de contato. Se a sua biblioteca for um sucesso (e minha própria experiência mostrou que esse também é o caso de outras desconhecidas), as pessoas encontrarão dificuldades com ela: erros ou simplesmente dificuldades para entender ou usar algumas partes dela. Muitas vezes, é útil receber o feedback deles para melhorar sua biblioteca: para todas as pessoas que relataram um problema, possivelmente existem centenas que, ao encontrá-lo, preferem simplesmente mudar para outra biblioteca.

Além disso:

1. Deixe claro se sua biblioteca funciona com Python 2 ou 3 ou ambos.

2. Se a biblioteca não funcionar no Windows, diga-o.

3. Certifique-se de usar as convenções oficiais (use pep8 para verificar). Caso contrário, explique-o claramente ou corrija-o.

4. Tome cuidado com o manuseio de casos extremos. Quando sua biblioteca é chamada com um tipo errado ou com um valor que não é suportado, deve-se dizer, em inglês puro, o que exatamente está errado. O que não deve ser feito é elevar uma exceção enigmática dez níveis abaixo da pilha e deixar o usuário descobrir o que deu errado.

Depois de usar algumas bibliotecas menos maduras ao longo dos anos, um conselho importante é que, depois de escolher sua ferramenta de implantação, faça o seguinte: Sua biblioteca faz algo realmente útil para criar uma comunidade?

Identifique as dependências da sua biblioteca.

Tente uma implantação em um ambiente limpo, em um contêiner de arquivo ou VM. Considero esta etapa crucial, pois muitas vezes há algo único em um ambiente pessoal que causa problemas.

Considere quem manterá a biblioteca no futuro, não há nada mais frustrante do que encontrar uma biblioteca que foi o projeto de estimação de alguém por três ou quatro anos e depois não obtém as atualizações necessárias para mantê-la atualizada.

Considere se você ou sua equipe querem assumir o compromisso de manter a biblioteca testada e documentada (testes de unidade e pipelines de IC começam a fazer parte da equação).

Talvez você possa encontrar um projeto OSS maduro em seu campo e contribuir com seu código para esse projeto? Pode haver algumas vantagens, como:

• Você pode maximizar sua contribuição. De fato, muitos projetos OSS de "hobby" são potencialmente valiosos, mas pouco utilizados pela comunidade (consulte a resposta @ReaddyEddy). É apenas um grande esforço preparar o projeto inicialmente, depois mantê-lo, divulgá-lo, fornecer exemplos e documentação adequados, etc.
• Muitos dos problemas técnicos que você mencionou já seriam resolvidos no projeto maduro.
• Se sua biblioteca agregar valor ao projeto OSS, seus colaboradores poderão ajudá-lo a elevar seu código aos padrões do projeto. Assim, você pode economizar esforço e ganhar experiência. Você também receberá respostas específicas sobre Sphinx, TravisCI, CookieCutter e outros aspectos técnicos.

Se houver um projeto OSS relevante que você goste e talvez use, por que não abrir um problema ou uma solicitação pull ou entrar em contato com os mantenedores? (Uma boa maneira de começar pode ser resolver um problema existente.)

É 2019, sugiro fortemente começar com as ferramentas mais modernas. Você não precisa de um setup.py, é algo que as pessoas da comunidade Python querem se livrar, e acredito que eventualmente o façam .

Tente poesia , você não vai se arrepender.

Esta é uma pergunta complicada que você está fazendo, e eu concordo plenamente com a resposta de Arseni . Boa documentação é um aspecto muito importante. Se eu não conseguir colocar sua biblioteca em funcionamento com algumas etapas simples, apenas a solto (a menos que eu esteja realmente ansioso para experimentá-la).

Algumas coisas que você definitivamente considera

• Pense em como você fará a versão da sua biblioteca. Você deseja ter compatibilidade com versões anteriores em algum nível e também correções de bugs ao longo da rota. Leia sobre versão semântica
• Você está usando o git de maneira relativamente linear (para desfazer). Você está familiarizado com a ramificação no git . Realmente não é tão difícil e facilita a vida. Uma vez que você se agarra aos galhos. Adapte um modelo de ramificação para seu repositório. Escolha as partes deste modelo de ramificação que considerar relevantes. Compare isso também com as ramificações dos repositórios que você está usando.
• Licenciamento: você deve fornecer uma licença para sua biblioteca. Como não sou especialista legal sobre esse assunto, posso compartilhar apenas um link para essa comparação entre licenças comuns . Não tome essa escolha de ânimo leve.
• Bugtracker. Você deseja que esse usuário possa fornecer relatórios de erros. Isso ajuda você a melhorar a qualidade do código. Para cada bug que você resolver, adicione um teste ao seu trabalho de estrutura de teste, o que garante que ele não seja travado no futuro (teste de regressão). Um sistema de rastreamento de bugs pode ser usado para solicitações de recursos.
• Contribuições de usuários. Deseja contribuições do usuário? Não tenho certeza de como isso normalmente funciona em produtos de código aberto, mas posso imaginar que você possa permitir que os usuários criem ramificações de recursos. Via github, você parece ser capaz de controlar isso através de solicitações pull

Como não tenho experiência relevante com Python, não posso dar nenhuma dica nessa direção. No entanto, é possível automatizar todos os testes acionados por cada confirmação no seu repositório remoto (por exemplo, usando o Jenkins ). No entanto, sugiro adiar isso, porque é muito trabalhoso configurar sem experiência anterior.

Essas são ótimas perguntas.

Sobre etapas incrementais concretas importantes em direção a uma biblioteca liberável:

• Separe os arquivos que se tornarão a biblioteca do restante do projeto.
  • A biblioteca deve entrar em seu próprio repositório git, mas você pode achar uma etapa intermediária útil colocá-la em um diretório de nível superior separado dentro do seu repositório atual. Quando você o tornar um repositório separado, armazene-o adjacente ao restante do seu projeto, que poderá ser consultado ../libraryaté que você chegue às etapas do empacotamento pip e do modo de desenvolvimento.
  • Todos os acessos do restante do projeto a esta biblioteca devem passar por sua API pública. Você pode encontrar algumas interdependências para separar.
• Escreva de forma incremental docstrings para documentar a API da biblioteca.
  • Eventualmente, as docstrings serão inseridas em uma ferramenta de documentação, mas o trabalho importante é escrever o texto que explica a API de maneira concisa e suficiente para outras pessoas. É mais fácil preenchê-lo um pouco de cada vez do que de uma só vez, e ficará muito melhor escrevendo rascunhos e voltando a ele mais tarde quando melhores explicações e exemplos vierem à mente.
  • Se você achar difícil documentar alguma parte da API, pergunte se essa parte da API tem espaço para melhorias. Poderia ser mais simples? Mais regular? É muito geral? Especializada demais? Poderia usar nomes mais familiares?
  • As docstrings podem documentar tipos de argumento usando comentários estruturados que as ferramentas podem verificar. Ainda não encontrei documentação real sobre isso, mas o PyCharm IDE ajudará a construir esses documentos e verificará imediatamente os tipos de argumentos ao editar chamadas de métodos.
  • Falando nisso, o PyCharm é uma ferramenta maravilhosa para economizar tempo do desenvolvedor e melhorar a qualidade do código. Ele executará "inspeções" para verificar o código enquanto você o edita, por exemplo, verificando tipos quando possível, verificando importações ausentes e não utilizadas, métodos duplicados, erros no estilo PEP 8 e assim por diante.
• Comece a escrever testes de unidade usando pytest. Muito antes de você fazer um lançamento, os testes de unidade serão recompensados ​​em seu próprio desenvolvimento, encontrando bugs em casos extremos e fornecendo confiança de que as alterações de código não quebraram as coisas. Novamente, você pode criar isso com o tempo. É muito fácil começar.
• Examine as bibliotecas de código aberto existentes (que são aproximadamente do mesmo tamanho) no GitHub para ver como elas organizam os arquivos e versões. Veja como eles fazem o rastreamento de bugs / problemas e recebem solicitações. Contribua com um ou mais deles para obter experiência com esses processos de organização de projeto com várias pessoas, se você não tiver experiência lá. O GitHub possui boas ferramentas para esses processos. Ele faz coisas agradáveis ​​com README.mdarquivos de documentação no nível superior e em qualquer diretório e com um arquivo de licença.
• Considere contratar um colaborador para obter feedback sobre a biblioteca, sua API e documentação.
  • Quando você for lançado, será útil ter um ou mais colaboradores para corrigir bugs durante as férias, ajudar a responder às perguntas dos usuários e, ao mesmo tempo, começar a fazer solicitações pull com revisões de código, dividir as tarefas de liberação da biblioteca, e trazer experiência adicional com gerenciamento de projetos e design de bibliotecas.
• Até agora você tem feito um histórico linear de commit do git. Eventualmente, será útil usar "ramificações de problemas" para correções e alterações específicas, "ramificações de liberação" para a execução controlada de uma liberação e "ramificações de desenvolvimento" para qualquer trabalho de várias pessoas em andamento que não esteja pronto para mesclar no ramo mestre. Portanto, reserve um dia ou dois ao longo do caminho para aprender sobre isso e comece a praticar com ele antes de precisar confiar nessas habilidades git. O git é muito flexível e útil, mas a interface do usuário pode ficar cheia .
  • Um lugar para ler sobre os ramos git e seus usos é no livro Pro Git . Das muitas maneiras de usar ramificações, comece com apenas "emitir ramificações".
  • O aplicativo GitHub Desktop é uma ótima ferramenta para gerenciar ramificações. Também é ótimo para fazer confirmações, pois facilita a gravação da mensagem de confirmação ao revisar todas as alterações.