Faraday: Solicitud de función: definiciones de método explícitas para verbos HTTP

Hola @dduugg , en lugar de definir explícitamente los métodos, exploraría una solución amigable con la documentación.
También usamos la definición de metaprogramación en la conexión: https://github.com/lostisland/faraday/blob/master/lib/faraday/connection.rb#L195

¿Funciona bien con los puntos que mencionaste anteriormente?
Si es así, también podríamos replicar un fragmento de documentación similar para el módulo Faraday .

Hola @iMacTia , gracias por la respuesta. No creo que el problema se pueda resolver con documentación. ¿Puedo molestarlo para que exponga la resistencia a las definiciones explícitas? Creo que eso enmarcaría mejor la discusión. Por ejemplo, es probable que un enfoque de documentación sea tan detallado (contando varias directivas @!method & @!scope , además del código method_missing ) que las siete definiciones de reenvío explícito de una línea Estoy sugiriendo en Faraday . Pero no sé si esa es la razón fundamental aquí (el código se lee mucho más de lo que está escrito, así que creo que la optimización para el escritor de código es un error de todos modos).

Hay principalmente 2 puntos que me ponen en la valla con este cambio.

• Personalmente, no creo que usar delegates sea ​​una ventaja solo para el escritor de código. He estado usando Ruby durante años y, como otros, llegué a apreciar la sintaxis sucinta de este lenguaje. Cuando leo un código y encuentro delegates , inmediatamente sé lo que eso significa y potencialmente puede condensar decenas de líneas de código en solo un par de ellas.
• Los proxies de verbos HTTP no son la única instancia en Faraday en la que aprovechamos la metaprogramación, hay muchas más instancias, que probablemente sufren el mismo problema que ha planteado aquí, pero que aún no se han notado. Aceptar este cambio hará una excepción o creará un precedente, ambas cosas me gustaría evitar.

Pero en lugar de centrarme en mi resistencia a este cambio, prefiero discutir qué tipo de ventajas estamos tratando de introducir aquí. Entiendo completamente el problema que está describiendo y, de hecho, creo que deberíamos intentar resolverlo si es posible.
Entonces, si el problema principal aquí es la compatibilidad con IDE / herramientas para sugerencias de código, autocompletar y documentación, entonces simplemente propongo encontrar una solución alternativa como comentarios de documentación (ya usamos YARD de manera bastante extensa).
Y también tiene razón cuando dice que esta solución es igual de detallada, aunque yo diría que un comentario no afectará la legibilidad tanto como una lista de métodos y es fácilmente reconocible.

Hola @iMacTia , gracias por tu respuesta. Hemos cambiado a una biblioteca diferente con una mejor capacidad de descubrimiento de API y soporte de herramientas, pero compartiré mis pensamientos en caso de que los encuentre útiles.

• La capacidad de descubrimiento no excluye el uso de la metaprogramación (aunque en este caso específico creo que def s explícitos son el camino a seguir), pero requeriría reemplazar el enfoque method_missing , como se describió anteriormente.
• No estoy seguro de entender el argumento delegates . Faraday no parece utilizar delegadores explícitos en el manejo de métodos de verbos HTTP. (La confusión en este punto es probablemente un olor a código de que la implementación de los métodos de verbos HTTP es demasiado complicada).
• Tendremos que estar de acuerdo en no estar de acuerdo en que delegate y similares son una ayuda para el escritor de código. Estoy trabajando con gente con un par de décadas de experiencia colectiva en ruby, y no hemos encontrado ningún beneficio de legibilidad para el enfoque aquí (incluso descontando el tiempo perdido para intentar explorar la API a través de palanca, YARD, sorbete y solargraph ). Puede valer la pena ver un intento rubyista de explorar esta API por primera vez, al menos en este punto específico.

Solo trato de proporcionar comentarios honestos (y con suerte útiles) aquí. Aún aprecio el tiempo y el esfuerzo en esta contribución al OSS.

¡Oye, gracias por todo tu arduo trabajo en Faraday! Sé que este es un problema antiguo, pero suelo estar de acuerdo en que la capacidad de descubrimiento es un problema. Estoy trabajando en un middleware y agregué esta sección a mi README. Mi biblioteca está dirigida a alguien que quizás no haya usado Faraday antes, así que me corresponde a mí explicar las cosas. Diré (algo vacilante) que no fue fácil descifrar las cosas.

@gurgeous Estoy de acuerdo en que la documentación es definitivamente un frente en el que podríamos estar haciendo un mejor trabajo (aunque comenzamos a abordar esto lanzando el sitio web de Faraday ), pero no veo cómo la sugerencia en este problema va a resolver su punto específico.

Tal vez me estoy perdiendo el punto porque simplemente estoy acostumbrado a trabajar de una manera diferente, pero si no sé cómo usar una biblioteca, no confío en el autocompletado y adivino para saber qué hacer.
En su lugar, reviso la documentación de la biblioteca y, si eso no ayuda, me sumerjo en el código para ver cómo funciona.

Por eso creo que una documentación mejorada (visual o en el código) es la forma de resolver esto.
¿Pero tal vez me falta algo aquí o un caso de uso particular en el que una mejor documentación no ayudaría?
¿Es correcta mi comprensión de la "capacidad de descubrimiento"?

¿Es correcta mi comprensión de la "capacidad de descubrimiento"?

No en mi caso. Mi expectativa era poder hacer ls Faraday en pry , seguido de $ Faraday.get , etc. si quería sumergirme en un método específico. Siento que he podido hacer esto de manera efectiva con cualquier otra gema que haya usado, rara vez (si es que alguna vez) necesito navegar a una página de documentación, por lo tanto, abrir este ticket. (Esto se suma a otros problemas mencionados anteriormente, como las herramientas de análisis estático que no reconocen el código que usa la biblioteca).

Gracias de nuevo por escucharnos.

¡Me encanta el sitio web de Faraday! ¿Quizás pueda enviar un PR con algunas sugerencias? Feliz de ayudar. Creo que ese tipo de esfuerzo siempre vale la pena para los recién llegados. Avísame si estarías interesado.

En términos de pry + ls Faraday , yo también soy fanático de ese patrón y lo uso mucho. Alejarse de method_missing no es una mala idea. Ruby está siendo arrastrado lentamente en esa dirección con el auge de Ruby 3, los servidores de idiomas, RBS, etc. Sin embargo, creo que esto es secundario a los documentos.

@gurgeous _Estamos_ interesados ​​en solicitudes de extracción de documentación, busque el directorio docs/ con un conjunto de Gemfile (y README) que se utiliza para publicar el sitio web en las páginas de GitHub, que estamos usando. Si su uso no está claro, el proceso de actualización del sitio web, abra un Issue o un PR para _that_, también.

¡Gracias por preocuparse por los usuarios de Faraday!

¡Me encanta el sitio web de Faraday! ¿Quizás pueda enviar un PR con algunas sugerencias? Feliz de ayudar. Creo que ese tipo de esfuerzo siempre vale la pena para los recién llegados. Avísame si estarías interesado.

@gurgeous absolutamente! Siempre agradecemos la ayuda para mejorar la documentación o el sitio web, ya que las cosas que son obvias para nosotros, los mantenedores, pueden no ser tan obvias para los usuarios. Además, realmente luchamos con el tiempo y eso a menudo tiene un costo para la documentación. En realidad, la documentación estaría en un estado mucho peor si no fuera por los esfuerzos @olleolleolle continuó 😄!

En el punto pry (cc @dduugg), nunca lo usé, por lo que probablemente no entendía.
Lo intenté con sus detalles adicionales y noté que ls Faraday::Connection muestra los métodos generados dinámicamente, así como los delegados 🙌.
Así que mi entendimiento original de que no podemos usar este tipo de "magia" Ruby estaba equivocado, y realmente el único límite está en usar missing_method .

Lo que no me gustó mucho fue la introducción de métodos explícitos como los siguientes:

def self.get(...)
  ...
end

def self.post(...)
  ...
end

# ... and so on ...

Pero si podemos arreglar el descubrimiento de pry agregando definiciones dinámicas o delegaciones al módulo principal Faraday , entonces eso es algo con lo que estaría bien. ¡Perdón por no haberlo recibido la primera vez!

No se preocupe por las limitaciones de tiempo. ¡Nunca te sientas mal por ser un mantenedor de código abierto! Agradecemos sus esfuerzos independientemente. Yo también he estado ahí ...

Comenzaré una discusión re: docs para asegurarme de que estamos en la misma página.

@iMacTia ¿Cómo sabría un usuario mirar en Faraday::Connection ? Desde entonces, cambié a una gema HTTP con una API detectable, pero eché un vistazo rápido a https://lostisland.github.io/faraday/usage/ y ninguno de los ejemplos de código lo usa explícitamente (aunque el último lo hace implícitamente). La mayoría de los ejemplos invocan métodos estáticos en Faraday , pero no se encuentran en palanca. No conozco ninguna otra joya que haya adoptado este enfoque, y sigo considerando que es un anti-patrón.

Gracias, como siempre, por escucharme.