Publicar diez CLIs en PyPI: lo que no te cuentan
Nombres ya ocupados, un limite de proyectos nuevos que no aparece en la documentación y por qué el nombre del paquete no tiene que coincidir con el del comando. Notas de publicar una suite completa de herramientas.
Tenía diez herramientas de línea de comandos con tests, CI y README, y pensaba que publicarlas en PyPI era la parte fácil: uv build, uv publish, siguiente. La parte técnica lo es. Lo que no esperaba era todo lo demás.
Los nombres buenos están ocupados (o casi). Tres de mis nombres ya existían en PyPI, y un cuarto — mlenv — fue rechazado por ser demasiado parecido a un proyecto existente, una regla anti-typosquatting que no conocía. La solución tiene truco: el nombre de distribución y el nombre del comando son cosas independientes. El paquete se llama mlenv-cli, pero lo que escribes en la terminal sigue siendo mlenv. Se instala pip install mlenv-cli, se usa mlenv. Cuatro de mis diez herramientas viven así, con nombre de paquete distinto del comando.
Existe un límite de proyectos nuevos, y no está documentado donde lo buscas. A partir del cuarto o quinto proyecto nuevo en poco tiempo, PyPI responde 429 Too many new projects created. No es por segundo ni por hora: es un límite de creación de proyectos nuevos con un enfriamiento largo, de horas o días. Publicar una suite entera de golpe no es el caso de uso previsto. Si planeas lanzar varias herramientas, cuenta con publicarlas en tandas a lo largo de varios días, no en una tarde.
El README se escribe antes de saber el nombre final. Consecuencia directa de lo anterior: mis README decían pip install mlenv semanas antes de descubrir que el paquete se llamaría mlenv-cli. La moraleja es reservar el nombre pronto — publicar una 0.1.0 mínima cuesta poco — o no comprometer el comando de instalación por escrito hasta tener el nombre confirmado.
Para las siguientes versiones: trusted publishing. Publicar con un token de API funciona, pero el token es un secreto de larga vida que alguien puede filtrar. GitHub Actions puede publicar en PyPI sin ningún secreto usando OIDC: PyPI confía en el repositorio y el workflow concretos que tú autorizas. Se configura una vez por proyecto y las releases pasan a ser un git tag. Para una suite de diez paquetes, la diferencia de mantenimiento es enorme.
Nada de esto es difícil; todo esto es fricción que no aparece en los tutoriales. Si vas a publicar tu primera herramienta, que sea esta la lista: nombre reservado pronto, instalación escrita con el nombre real, tandas si son varias, y OIDC para no gestionar tokens.
¿Conectamos?
Hablemos: feedback, colaboración o una oportunidad.
Puedes escribirme por un proyecto, una duda técnica, para darme feedback o por unas prácticas o un primer puesto junior. Respondo siempre.
Escríbeme
