Download de cookie - Download do código -fonte cookie

cookie

Código-Fonte de IA

2024.08.19

Baixar

Scientific Python: Guia, Cookie e SP-Repo-Review

Cookie

Um modelo de copiadora/cookieCutter para novos projetos Python com base no Guia do Developer Scientific Python. O que torna isso diferente de outros modelos para pacotes Python?

Vive com o Guia de Desenvolvimento do Python Scientific: toda decisão é claramente documentada e todas as ferramentas descritas, e tudo é mantido em sincronia.
Nove back -ends diferentes para escolher para construir pacotes.
Versão opcional de VCS para a maioria dos back -ends.
Geração de modelos testados em ações do GitHub usando NOX.
Suporta geração com copiadora, CookieCutter e Cruft.
Suporta ações do GitHub se direcionar um URL github.com (o padrão) e adicionar suporte experimental do GitLab CI de outra forma.
Inclui vários backnds compilados usando o PYBIND11, com rodas produzidas para todas as plataformas usando o Cibuild Wheel.
Fornece sp-repo-review para avaliar os repositórios existentes em relação às diretrizes, com uma versão WebAssembly integrada ao guia. Todas as verificações reticuladas.
Segue as melhores práticas do Pypa e atualizou regularmente.

Certifique-se de ter lido o Guia de Desenvolvimento do Python científico primeiro e possivelmente os usou em um projeto ou dois. Este não é um exemplo ou tutorial mínimo. É uma coleção de ferramentas úteis para iniciar um novo projeto usando CookieCutter ou para copiar em arquivos individuais para um projeto existente (manualmente, de {{cookiecutter.project_name}}/ ).

Durante a geração, você pode selecionar entre os seguintes back -end para o seu pacote:

Hatch: Isso usa Hatchling, um construtor moderno com boa inclusão de arquivos, extensível por meio de plugins e boas mensagens de erro. (Recomendado para projetos Python Pure)
FLIT: Um sistema moderno e leve Pep 621 Build para projetos Python puros. Substitui o setupTools, sem manifesto.in, setup.py ou setup.cfg. Baixa curva de aprendizado. Fácil de inicializar em novas distribuições. Difícil de incluir os arquivos certos, pouco suporte de metadados dinâmicos.
PDM: Uma solução all-in-one moderna e menos opinativa para projetos de python puros que suportam padrões. Substitui SetupTools, Venv/Pipenv, Pip, Wheel e Twine. Suporta PEP 621.
Poesia: uma solução tudo em um para projetos Python puros. Substitui SetupTools, Venv/Pipenv, Pip, Wheel e Twine. Curva de ensino superior, mas é tudo em um. Faz algumas suposições padrão ruins para as bibliotecas. O único com uma configuração não padrão do PyProject.toml.
SETUPTOLS: o sistema de construção clássico, mas com a nova configuração padronizada.
PYBIND11: Isso é setUptools, mas com uma extensão C ++ escrita no PYBIND11 e as rodas geradas pelo Cibuild Wheel.
Scikit-Build: um projeto Scikit-Build (CMake) também usando o PYBIND11, usando o Scikit-Build-Core. (Recomendado para projetos C ++)
Meson-Python: um projeto de meson também usando o PYBIND11. (Sem versão do VCS)
Maturin: um construtor PEP 621 para extensões binárias de ferrugem. (Sem versão do VCS) (recomendado para projetos de ferrugem)

Atualmente, a melhor opção é provavelmente a escotilha para projetos Python Pure, e a Scikit-Build (como a escolha Scikit-Build-Core + Pybind11) para projetos binários.

Para usar (versão moderna da copiadora)

Instale copier e copier-templates-extensions . Usando PIPX, isso é:

pipx install copier
pipx inject copier copier-templates-extensions

Agora, execute a copiadora para gerar seu projeto:

copier copy gh:scientific-python/cookie < pkg > --trust

( <pkg> é o caminho para colocar o novo projeto. Se a copiadora for antiga, use --UNSAFE em vez de --trust )

Você obterá uma experiência mais agradável da CLI com a validação de respostas. Você também receberá um arquivo .copier-answers.yml , que permitirá que você execute atualizações no futuro.

Nota: add --vcs-ref=HEAD para obter a versão mais recente em vez da última versão marcada; A cabeça sempre passa testes (e é o que o Cookiecutter usa).

Para usar (versão clássica do cookiecutter)

Instale o CookiecTutter, idealmente com brew install cookiecutter se você usar o Brew, caso contrário, com pipx install cookiecutter (ou Prenda pipx run no comando abaixo e pule a instalação). Em seguida, corra:

cookiecutter gh:scientific-python/cookie

Se você estiver usando o Cookiecutututter 2.2.3+, receberá boas descrições para as opções como a Copiadora!

Para usar (versão clássica de Cruft)

Você também pode usar o Cruft, o que adiciona a atualização de habilidades aos projetos de cozinheiro. Instale com pipx install cruft (ou prenda pipx run no comando abaixo e pule a instalação). Em seguida, corra:

cruft create gh:scientific-python/cookie

Pós -geração

Verifique os arquivos de configuração da chave, pyproject.toml e possivelmente setup.cfg e setup.py (exemplo pybind11). Atualize README.md . Atualize também e adicione documentos aos docs/ .

Existem algumas dependências de exemplo e uma versão mínima do Python do 3.9, sinta -se à vontade para alterá -la para o que você realmente precisar/deseja. Há também uma estrutura básica de backports com um pequeno exemplo de digitação.

Componentes contidos:

As ações do GitHub executam testes para a própria geração
- Usa NOx para que o desenvolvimento de biscoitos possa ser verificado localmente
Ações do GitHub implantam
- Os backnds de C ++ incluem Cibuild Wheel for Wheel Builds
- Usa a implantação do Publisher Trusted Publisher
Depende
Formatação tratada por pré-compromisso
- Nenhuma razão para não ser rigorosa em um novo projeto; Remova o que você não quer.
- Inclui mypy - digitação estática
- Inclui Ruff - formatação padrão, linha e autofixes
  - Substitui Flake8, Isort, Pyupgrade, Yesqa, Pycln e dezenas de plugins
- Inclui verificação de ortografia
Um alvo Pylint NOX pode ser usado para executar o Pylint, que integrou as anotações GHA
Uma pasta Sphinx Docs pronta para leitura e ReadThEdocs e [docs] extra
Uma pasta de teste e pytest [test] extra
Um NOxFile está incluído com alguns alvos comuns

Para desenvolvedores:

Você pode testar localmente com NOX:

# See all commands
nox -l

# Run a specific check
nox -s "lint(scikit-build)"

# Run a noxfile command on the project noxfile
nox -s "nox(hatch)" -- docs

Se você não possui nox localmente, pode usar o PIPX, como pipx run nox .

Outros projetos semelhantes

O Hypermodern-Python é outro projeto que vale a pena conferir com muitas semelhanças, como ótima documentação para cada recurso e muitas das mesmas ferramentas usadas. Ele possui um conjunto de recursos ligeiramente diferentes e tem um foco mais forte nas ações do GitHub - a maioria do nosso guia pode ser adaptada a um sistema de IC diferente com bastante facilidade se você não quiser usar o GHA. Também força o uso da poesia (em vez de ter uma seleção de back -end) e não suporta projetos compilados. Atualmente, ele despeja todas as dependências de desenvolvimento em um ambiente compartilhado, causando longos tempos de resolução e alta chance de conflitos. Ele também não usa pré-compromisso da maneira como deveria ser usada. Ele também possui bastante código personalizado.

História

Muito do guia, o CookieCutter e o Repo-Review começou como parte do Scikit-Hep. Esses projetos foram mesclados, generalizados e combinados com o Guia NSLS-II durante a cúpula de desenvolvedores de Python científica de 2023.

SP-Repo-Review

sp-repo-review fornece cheques com base no Guia de Desenvolvimento do Python Scientific em Scientific-Python/Cookie para Repo-Review.

Esta ferramenta pode verificar o estilo de um repositório. Use assim:

pipx run ' sp-repo-review[cli] ' < path to repository >

Isso produzirá uma lista de resultados - marcas de verificação verdes significam que essa regra é seguida, o Red X significa que a regra não é. Um sinal de aviso amarelo significa que o cheque foi ignorado porque uma verificação necessária anterior falhou. Alguns verificações falharão, tudo bem - o objetivo é levar todos os problemas possíveis à sua atenção, não forçar a conformidade com verificações arbitrárias. Eventualmente, pode haver uma maneira de marcar as verificações como ignoradas.

Por exemplo, GH101 espera que todos os seus arquivos de ação tenham um bom name: Campo. Se você estiver satisfeito com os nomes baseados em arquivos que você vê no CI, deve sentir-se à vontade para simplesmente ignorar essa verificação (basta ignorá-la visualmente no momento, uma maneira de especificar cheques ignorados provavelmente será adicionada eventualmente).

Todas as verificações são mencionadas pelo menos de alguma forma no Guia de Desenvolvimento do Python Scientific. Você deve ler isso primeiro - se não estiver tentando segui -los, alguns dos cheques podem não funcionar. Por exemplo, as diretrizes especificam a configuração de pytest ser colocada em pyproject.toml . Se você o colocar em outro lugar, todas as verificações de pytest serão ignoradas.

Isso foi originalmente desenvolvido para o Scikit-Hep antes de se mudar para o Scientific Python.

Outras maneiras de usar

Você também pode usar ações do GitHub:

- uses : scientific-python/cookie@<version>

Ou pré-compromisso:

- repo : https://github.com/scientific-python/cookie
  rev : <version>
  hooks :
    - id : sp-repo-review

Se você usar additional_dependencies para adicionar mais plug-ins, como validate-pyproject , também deverá incluir "repo-review[cli]" para garantir que os requisitos da CLI sejam incluídos.