You are viewing a plain text version of this content. The canonical link for it is here.
Posted to github@arrow.apache.org by "aiguofer (via GitHub)" <gi...@apache.org> on 2023/06/01 04:07:59 UTC
[GitHub] [arrow-adbc] aiguofer opened a new pull request, #724: docs: add docs for Python Flight SQL Driver, add link to Go Snowflake driver
aiguofer opened a new pull request, #724:
URL: https://github.com/apache/arrow-adbc/pull/724
TODO: I wasn't very sure where to put this. Organization for seems a little strange with a couple of different sections for language specific stuff. Let me know if you want me to re-organize.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow-adbc] lidavidm commented on a diff in pull request #724: docs: add docs for Python Flight SQL Driver, add link to Go Snowflake driver
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on code in PR #724:
URL: https://github.com/apache/arrow-adbc/pull/724#discussion_r1214622201
##########
docs/source/python/flight_sql.rst:
##########
Review Comment:
The problem then is having to duplicate and update information across several pages.
Would it work better to just have one page per driver (all languages on that page)?
That said, for this PR I'd prefer if we could keep the existing organization rather than having half/half.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow-adbc] aiguofer commented on a diff in pull request #724: docs: add docs for Python Flight SQL Driver, add link to Go Snowflake driver
Posted by "aiguofer (via GitHub)" <gi...@apache.org>.
aiguofer commented on code in PR #724:
URL: https://github.com/apache/arrow-adbc/pull/724#discussion_r1224917734
##########
docs/source/python/flight_sql.rst:
##########
Review Comment:
Sweet! yeah I like that organization much better! I'll add my examples into the python blocks for the FlightSQL driver
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow-adbc] lidavidm commented on a diff in pull request #724: docs: add docs for Python Flight SQL Driver, add link to Go Snowflake driver
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on code in PR #724:
URL: https://github.com/apache/arrow-adbc/pull/724#discussion_r1223129388
##########
docs/source/python/flight_sql.rst:
##########
Review Comment:
That is fair.
I'll try to reorg things a bit in https://github.com/apache/arrow-adbc/issues/738. My tentative plan is to rename `Langauge-Specific APIs` to `API Reference`, and move the usage examples to solely be under `Tutorials`. And then I'll make all driver pages top-level.
The goal is to have the same general functionality for each driver in each language. That is mostly accomplished by having one implementation of each driver, with bindings to the rest of the languages. (Java is a bit of an exception.)
I've also wanted to have an Arrow Cookbook style reference as well, but not sure if that should be a separate thing, or (as here) on each driver page.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow-adbc] lidavidm merged pull request #724: docs: add docs for Python Flight SQL Driver, add link to Go Snowflake driver
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm merged PR #724:
URL: https://github.com/apache/arrow-adbc/pull/724
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow-adbc] aiguofer commented on a diff in pull request #724: docs: add docs for Python Flight SQL Driver, add link to Go Snowflake driver
Posted by "aiguofer (via GitHub)" <gi...@apache.org>.
aiguofer commented on code in PR #724:
URL: https://github.com/apache/arrow-adbc/pull/724#discussion_r1214619448
##########
docs/source/python/flight_sql.rst:
##########
Review Comment:
I thought about this, but as a user looking for information on how to use the Python bindings, you wouldn't think of clicking on the Go section. While I was trying to figure out how to use this I struggled to find consistency on what's in the Go page vs what's in the C/C++/Python page.
The current organization might make more sense for people who are deep in the project and understand the relationships between the various language implementations. However, IMO the docs should be tailored to potential users looking to use ADBC in their preferred language. I started thinking about reorganizing all of this but didn't want to make my PR too invasive. I feel like an organization like the following would be really helpful for users:
* Language (one per language)
* ADBC Manager description (what is it, how does it work
* Usage Example (code of how to query, fetch results, look up metadata, etc)
* If multiple APIs are available (like dbapi for python), brief description and explanation of each... or simply using the "tabs" for code blocks showing how to do it with each api
* Driver (one per available driver)
* How to install
* Example code to use
* Available DB, connection, and statement options (this could be a link to the underlying implementation driver, or the API for the language if it has some enum/dataclass/struct describing the options in code)
Under an organization like ^, the current `Python quickstart` could just be moved to the Python section for `Usage Example`
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow-adbc] aiguofer commented on a diff in pull request #724: docs: add docs for Python Flight SQL Driver, add link to Go Snowflake driver
Posted by "aiguofer (via GitHub)" <gi...@apache.org>.
aiguofer commented on code in PR #724:
URL: https://github.com/apache/arrow-adbc/pull/724#discussion_r1214637937
##########
docs/source/python/flight_sql.rst:
##########
Review Comment:
Yeah it's possible that a single page per driver is better; it's not as easy to use from a user perspective, but it's a good tradeoff between maintainability and user experience. If the goal is to have the same general options and descriptions for all languages, then this is fine. If there's lots of exceptions (works on this language but not on that) then this could be cumbersome.
Part of the issue is that it's already kind of half/half. When you look under `LANGUAGE-SPECIFIC APIS` there's still some usage examples, and then there's the random `Python quickstart` page.
All that being said, I'll move the code examples into `go/flight_sql.rst` for now.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow-adbc] lidavidm commented on a diff in pull request #724: docs: add docs for Python Flight SQL Driver, add link to Go Snowflake driver
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on code in PR #724:
URL: https://github.com/apache/arrow-adbc/pull/724#discussion_r1214354159
##########
docs/source/python/flight_sql.rst:
##########
Review Comment:
This should go in the 'Go' section. The Python driver just uses Go.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow-adbc] lidavidm commented on a diff in pull request #724: docs: add docs for Python Flight SQL Driver, add link to Go Snowflake driver
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on code in PR #724:
URL: https://github.com/apache/arrow-adbc/pull/724#discussion_r1223420044
##########
docs/source/python/flight_sql.rst:
##########
Review Comment:
Implemented in #746
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org