Convertir un proyecto personal de Python en una biblioteca liberable

Soy un académico más que un programador, y tengo muchos años de experiencia escribiendo programas de Python para mi propio uso, para apoyar mi investigación. Es probable que mi último proyecto sea útil para muchos otros y para mí, y estoy pensando en lanzarlo como una biblioteca Python de código abierto.

Sin embargo, parece que hay muchos obstáculos para pasar de un proyecto personal en funcionamiento a una biblioteca que otros puedan instalar y usar sin problemas. Esta pregunta es sobre los primeros pasos que debo tomar para comenzar a trabajar hacia un lanzamiento público.

Actualmente, tengo un único repositorio de git que contiene mi código que usa la biblioteca y la biblioteca en sí, y uso git como un botón de deshacer de emergencia en caso de que algo se rompa. Todo esto funciona bien para un solo usuario, pero obviamente no es apropiado si quiero liberarlo. Donde quiero terminar es que mi biblioteca está en un repositorio separado y que otros pueden instalarla pip, y tiene una API estable.

Aprender a usar setuptools, etc., probablemente no sea tan difícil una vez que esté a punto de querer publicarlo; mi problema es saber cómo debería estar trabajando para llegar a ese punto.

Entonces, mi pregunta es, ¿cuáles son los primeros pasos que uno debe tomar para comenzar a preparar un proyecto de biblioteca Python para el consumo público? ¿Cómo debo reorganizar la estructura de mi directorio, el repositorio de git, etc. para comenzar a trabajar en una versión pública de la biblioteca?

En términos más generales, sería muy útil si hay recursos que se sabe que son útiles al intentar esto por primera vez. Los consejos sobre las mejores prácticas y los errores a evitar, etc., también serían muy útiles.

Algunas aclaraciones: las respuestas actuales abordan una pregunta en la línea de "¿cómo puedo hacer que mi biblioteca de Python sea buena para que otros la usen?" Esto es útil, pero es diferente de la pregunta que pretendía hacer.

Actualmente estoy al comienzo de un largo viaje hacia el lanzamiento de mi proyecto. El núcleo de mi implementación funciona (y funciona muy bien), pero me siento abrumado por la cantidad de trabajo que tengo por delante y estoy buscando orientación sobre cómo navegar por el proceso. Por ejemplo:

• Mi código de biblioteca está actualmente acoplado a mi propio código específico de dominio que lo usa. Vive en una subcarpeta y comparte el mismo repositorio git. Eventualmente, tendrá que convertirse en una biblioteca independiente y colocarse en su propio repositorio, pero sigo postergando esto porque no sé cómo hacerlo. (Ni cómo instalar una biblioteca en 'modo de desarrollo' para que aún pueda editarla, ni cómo mantener sincronizados los dos repositorios de git).

• Mis cadenas de documentos son concisas, porque sé que eventualmente tendré que usar Sphinx o alguna otra herramienta. Pero estas herramientas no parecen ser fáciles de aprender, por lo que se convierte en un subproyecto importante y sigo posponiéndolo.

• En algún momento necesito aprender a usar setuptools o alguna otra herramienta para empaquetarlo y rastrear las dependencias, que son bastante complejas. No estoy seguro de si necesito hacer esto ahora o no, y la documentación es un laberinto absoluto para un nuevo usuario, así que sigo decidiendo hacerlo más tarde.

• Nunca he tenido que hacer pruebas sistemáticas, pero definitivamente lo haré para este proyecto, así que tengo que (i) aprender lo suficiente sobre las pruebas para saber qué metodología es la adecuada para mi proyecto; (ii) aprender qué herramientas están disponibles para mi metodología elegida; (iii) aprender a usar mi herramienta elegida; (iv) implementar conjuntos de pruebas, etc. para mi proyecto. Este es un proyecto en sí mismo.

• Puede que haya otras cosas que tengo que hacer también. Por ejemplo, jonrsharpe publicó un enlace útil que menciona git-flow, tox, TravisCI, virtualenv y CookieCutter, ninguno de los cuales había escuchado antes. (La publicación es de 2013, por lo que también tengo que hacer un trabajo para averiguar cuánto sigue vigente).

Cuando juntas todo esto, es una gran cantidad de trabajo, pero estoy seguro de que puedo hacerlo todo si sigo enchufándolo, y no tengo prisa. Mi problema es saber cómo dividirlo en pasos manejables que se pueden hacer uno a la vez.

En otras palabras, estoy preguntando cuáles son los pasos concretos más importantes que puedo tomar ahora, para llegar a un producto liberable eventualmente. Si tengo un fin de semana gratis, ¿en cuáles de estas cosas debería centrarme? ¿Qué (si hay) se puede hacer de forma aislada de los demás, para que al menos pueda dar un paso sin necesidad de hacer todo? ¿Cuál es la forma más eficiente de aprender estas cosas para que aún tenga tiempo de concentrarme en el proyecto en sí? (Teniendo en cuenta que todo esto es esencialmente un proyecto de pasatiempo, no mi trabajo). ¿Hay algo que realmente no necesite hacer , ahorrándome una gran cantidad de tiempo y esfuerzo?

Todas las respuestas son muy apreciadas, pero agradecería especialmente las respuestas que se centran en estos aspectos de gestión de proyectos, con referencia específica al desarrollo moderno de Python.

Agregar un archivo setup.py, aunque es necesario, no es el paso más importante si desea que se use su biblioteca. Lo más importante es agregar documentación y anunciar su biblioteca. Dado que el segundo punto depende en gran medida de la biblioteca, permítanme centrarme en el aspecto de la documentación.

1. Sabes todo sobre tu biblioteca. Y esto es problemático. Ya sabe cómo instalarlo y cómo usarlo, por lo que muchas cosas pueden parecerle intuitivas o simplemente obvias. Desafortunadamente, las mismas cosas pueden no ser obvias ni intuitivas para los usuarios. Intenta mirar tu biblioteca como si no supieras nada al respecto y, lo que es más importante, pide a otras personas que la usen y trata de detectar todas las dificultades que tuvieron.

2. Explique, en inglés simple, de qué trata su biblioteca. Demasiadas bibliotecas suponen que todos las conocen. Cuando este no es el caso, puede ser difícil comprender cuál es el propósito de la biblioteca.

3. Escriba documentación técnica detallada, pero también no se olvide de piezas cortas de código que muestran cómo hacer algunas de las tareas con su biblioteca. La mayoría de los desarrolladores tienen prisa, y si necesitan pasar horas tratando de entender cómo hacer algo básico, pueden tender a cambiar a otras bibliotecas.

4. Incluya su información de contacto. Si su biblioteca es un éxito (y mi propia experiencia ha demostrado que este es el caso incluso para las más bien desconocidas también), las personas encontrarían dificultades con ella: errores o simplemente dificultades para comprender o usar algunas partes de ella. A menudo es útil recibir sus comentarios para mejorar su biblioteca: por cada persona que informó un problema, posiblemente haya cientos de personas que, al encontrarlo, prefieran cambiar a otra biblioteca.

Además de eso:

1. Deje en claro si su biblioteca funciona con Python 2 o 3 o ambos.

2. Si la biblioteca no funciona en Windows, dígalo.

3. Asegúrese de usar convenciones oficiales (use pep8 para verificar). Si no, explíquelo claramente o arréglelo.

4. Tenga cuidado al manejar casos extremos. Cuando se llama a su biblioteca con un tipo incorrecto o con un valor que no es compatible, debería decir, en inglés simple, qué es exactamente lo que está mal. Lo que no debería hacer es elevar una excepción críptica diez niveles más abajo y dejar que el usuario descubra qué salió mal.

Después de haber utilizado algunas bibliotecas menos que maduras a lo largo de los años, un consejo clave es que, una vez que haya elegido su herramienta de implementación, haga lo siguiente: ¿Su biblioteca hace algo realmente útil para construir una comunidad?

Identifica las dependencias de tu biblioteca.

Intente una implementación en un entorno limpio, ya sea un contenedor de expediente o VM. Considero que este paso es crucial, ya que a menudo hay algo único en un entorno personal que causa problemas.

Considere quién va a mantener la biblioteca en el futuro, no hay nada más frustrante que encontrarse con una biblioteca que fue el proyecto favorito de alguien durante tres o cuatro años y luego no recibe las actualizaciones necesarias para mantenerla actualizada.

Considere si usted o su equipo desean comprometerse a mantener la biblioteca probada y documentada (las pruebas unitarias y las canalizaciones de CI comienzan a formar parte de la ecuación aquí).

¿Quizás podría encontrar un proyecto OSS maduro en su campo y contribuir con su código a ese proyecto? Podría haber algunas ventajas, como:

• Puedes maximizar tu contribución. De hecho, muchos proyectos OSS "hobby" son potencialmente valiosos pero la comunidad los utiliza poco (véase la respuesta @ReaddyEddy). Es solo un gran esfuerzo hacer que el proyecto esté al principio inicialmente, luego mantenerlo, publicitarlo, proporcionar ejemplos y documentación adecuados, etc.
• Muchos de los problemas técnicos que mencionó ya estarían resueltos en el proyecto maduro.
• Si su biblioteca agrega valor al proyecto OSS, sus colaboradores podrían ayudarlo a actualizar su código a los estándares del proyecto. Para que pueda ahorrar esfuerzo y ganar experiencia. También obtendrá respuestas específicas sobre Sphinx, TravisCI, CookieCutter y otros aspectos técnicos.

Si hay un proyecto de OSS relevante que le gusta y puede usar, ¿por qué no abrir un problema o una solicitud de extracción o ponerse en contacto con los encargados de mantenimiento? (Una buena forma de comenzar podría ser resolver un problema existente).

Es 2019, sugiero comenzar con las herramientas más modernas. No necesita un setup.py, eso es algo de lo que la gente de la comunidad de Python quiere deshacerse, y creo que eventualmente lo harán.

Prueba Poesía , no te arrepentirás.

Esta es una pregunta complicada que está haciendo, y estoy completamente de acuerdo con la respuesta de Arseni . La buena documentación es un aspecto muy importante. Si no logro poner en funcionamiento su biblioteca con unos simples pasos, simplemente la dejaré allí (a menos que esté realmente ansioso por probarla).

Algunas cosas que definitivamente consideras

• Piensa en cómo vas a versionar tu biblioteca. Desea tener compatibilidad con versiones anteriores hasta cierto nivel, y también correcciones de errores a lo largo de la ruta. Lea sobre versiones semánticas
• Estás usando git de una manera relativamente lineal (para deshacer). Estás familiarizado con ramificación en git ? Realmente no es tan difícil y hace la vida más fácil. Una vez que te agarras con ramas. Adapte un modelo de ramificación para su repositorio. Elija las partes de este modelo de ramificación que considere relevantes. También compare esto con las ramas de los repositorios que está utilizando.
• Licencias: debe proporcionar una licencia para su biblioteca. No soy un experto legal en este asunto, por lo que solo puedo compartir un enlace a esta comparación entre licencias comunes . No tome esta elección a la ligera.
• Localizador de bichos. Desea que ese usuario pueda proporcionarle informes de errores. Esto le ayuda a mejorar la calidad del código. Para cada error que resuelva, agregue una prueba a su marco de prueba, lo que garantiza que no se frene en el futuro (prueba de regresión). Se puede utilizar un sistema de seguimiento de errores para solicitudes de funciones.
• Contribuciones de los usuarios. ¿Quieres contribuciones de los usuarios? No estoy seguro de cómo funciona esto normalmente en productos de código abierto, pero puedo imaginar que puede permitir a los usuarios crear ramas de características. A través de github parece que puede controlar esto mediante solicitudes de extracción

No tengo experiencia relevante con Python, por lo que no puedo darle ninguna pista en esa dirección. Sin embargo, es posible automatizar todas las pruebas activadas por cada confirmación en su repositorio remoto (es decir, utilizando Jenkins ). Sin embargo, sugiero posponer esto, porque es mucho trabajo configurarlo sin experiencia previa.

Estas son buenas preguntas.

Acerca de pasos incrementales concretos importantes hacia una biblioteca liberable:

• Separe los archivos que se convertirán en la biblioteca del resto del proyecto.
  • La biblioteca debe ir a su propio repositorio de git, pero es posible que le resulte un paso intermedio útil para colocarlo en un directorio separado de nivel superior dentro de su repositorio actual. Cuando lo convierta en un repositorio separado, guárdelo junto al resto de su proyecto, que luego puede consultarlo ../libraryhasta llegar a los pasos del modo de desarrollo y empaquetado de pip.
  • Todos los accesos del resto del proyecto a esta biblioteca deben pasar por su API pública. Puede encontrar algunas interdependencias para separar.
• Escriba incrementalmente cadenas de documentos para documentar la API de la biblioteca.
  • Eventualmente, las cadenas de documentos se alimentarán en una herramienta de documentación, pero el trabajo importante es escribir el texto que explica la API de manera concisa y suficiente a otras personas. Es más fácil completarlo un poco a la vez que todo a la vez, y saldrá mucho mejor escribiendo borradores y volviendo a ello más tarde cuando se me ocurran mejores explicaciones y ejemplos.
  • Si encuentra que alguna parte de la API es difícil de documentar, pregunte si esa parte de la API tiene margen de mejora. ¿Podría ser más simple? ¿Más regular? ¿Es demasiado general? Demasiado especializado? ¿Podría usar nombres más familiares?
  • Las cadenas de documentos pueden documentar tipos de argumentos mediante comentarios estructurados que las herramientas pueden verificar. Todavía no he encontrado documentación real sobre eso, pero el IDE de PyCharm ayudará a construir esas cadenas de documentos e inmediatamente verificará los tipos de argumentos mientras edita las llamadas a métodos.
  • Hablando de eso, PyCharm es una herramienta maravillosa para ahorrar tiempo al desarrollador y mejorar la calidad del código. Ejecutará "inspecciones" para verificar el código mientras lo edita, por ejemplo, verificando los tipos cuando puede, buscando importaciones faltantes y no utilizadas, métodos duplicados, errores de estilo PEP 8, etc.
• Comience a escribir pruebas unitarias usando pytest . Mucho antes de realizar un lanzamiento, las pruebas unitarias darán resultado en su propio desarrollo al encontrar errores en los casos de esquina y proporcionar confianza de que los cambios en el código no estropearon las cosas. De nuevo, puedes construir esto con el tiempo. Es bastante fácil comenzar.
• Examine las bibliotecas de código abierto existentes (que son aproximadamente del mismo tamaño) en GitHub para ver cómo organizan los archivos y las versiones. Observe cómo hacen el seguimiento de errores / problemas y las solicitudes de extracción. Contribuya a uno o más de ellos para obtener experiencia con estos procesos de organización de proyectos de varias personas si no tiene experiencia allí. GitHub tiene buenas herramientas para estos procesos. Hace cosas buenas con los README.mdarchivos de documentación en el nivel superior y en cualquier directorio, y con un archivo de licencia.
• Considere contratar a un colaborador para obtener comentarios sobre la biblioteca, su API y la documentación.
  • Cuando liberes, será útil tener uno o más colaboradores para corregir errores cuando estés de vacaciones, para ayudar a responder las preguntas de los usuarios y, mientras tanto, comenzar a hacer solicitudes de extracción con revisiones de código, para repartir las tareas de liberación de la biblioteca, y aportar experiencia adicional con la gestión de proyectos y el diseño de bibliotecas.
• Hasta ahora has estado haciendo un historial lineal de git commit. Eventualmente, será útil usar "ramas de problemas" para arreglos y cambios específicos, "ramas de lanzamiento" para el período de ejecución controlado de un lanzamiento y "ramas de desarrollo" para cualquier trabajo en progreso de varias personas que no esté listo para fusionarse en la rama maestra. Por lo tanto, reserve un día o dos en el camino para aprender sobre esto y comience a practicar antes de que necesite confiar en esas habilidades de git. git es muy flexible y útil, pero la interfaz de usuario puede ser complicada .
  • Un lugar para leer sobre las ramas de git y sus usos es en el libro Pro Git . De las muchas formas de usar ramas, comience simplemente con "ramas de emisión".
  • La aplicación de escritorio GitHub es una gran herramienta para administrar sucursales. También es excelente para realizar confirmaciones, ya que facilita la escritura del mensaje de confirmación mientras revisa todos los cambios.