PKG-INFO 6.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169
  1. Metadata-Version: 2.1
  2. Name: phoenixdb
  3. Version: 1.2.1
  4. Summary: Phoenix database adapter for Python
  5. Home-page: http://phoenix.apache.org/python.html
  6. Author: Apache Software Foundation
  7. Author-email: dev@phoenix.apache.org
  8. License: Apache 2
  9. Platform: UNKNOWN
  10. Classifier: Programming Language :: Python
  11. Classifier: Programming Language :: Python :: 2
  12. Classifier: Programming Language :: Python :: 2.7
  13. Classifier: Programming Language :: Python :: 3
  14. Classifier: Programming Language :: Python :: 3.5
  15. Classifier: Programming Language :: Python :: 3.6
  16. Classifier: Programming Language :: Python :: 3.7
  17. Classifier: Programming Language :: Python :: 3.8
  18. Classifier: Programming Language :: Python :: 3.9
  19. Classifier: Programming Language :: Python :: 3.10
  20. Provides-Extra: SQLAlchemy
  21. License-File: LICENSE
  22. License-File: NOTICE
  23. Phoenix database adapter for Python
  24. ===================================
  25. ``phoenixdb`` is a Python library for accessing
  26. `Apache Phoenix <http://phoenix.apache.org/>`_
  27. using the
  28. `remote query server <http://phoenix.apache.org/server.html>`_.
  29. This library implements the
  30. standard `DB API 2.0 <https://www.python.org/dev/peps/pep-0249/>`_ interface and a
  31. subset of `SQLAlchemy <https://www.sqlalchemy.org/>`_, either of which should be familiar
  32. to most Python programmers.
  33. Installation
  34. ------------
  35. The source code is part of the phoenix-queryserver source distribution.
  36. You can download it from <https://phoenix.apache.org/>, or get the latest development version
  37. from <https://github.com/apache/phoenix-queryserver>
  38. Extract the archive and then install it manually::
  39. cd /path/to/phoenix-queryserver-x.y.z/python/phoenixdb
  40. python setup.py install
  41. Usage
  42. -----
  43. The library implements the standard DB API 2.0 interface, so it can be
  44. used the same way you would use any other SQL database from Python, for example::
  45. import phoenixdb
  46. import phoenixdb.cursor
  47. database_url = 'http://localhost:8765/'
  48. conn = phoenixdb.connect(database_url, autocommit=True)
  49. cursor = conn.cursor()
  50. cursor.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, username VARCHAR)")
  51. cursor.execute("UPSERT INTO users VALUES (?, ?)", (1, 'admin'))
  52. cursor.execute("SELECT * FROM users")
  53. print(cursor.fetchall())
  54. cursor = conn.cursor(cursor_factory=phoenixdb.cursor.DictCursor)
  55. cursor.execute("SELECT * FROM users WHERE id=1")
  56. print(cursor.fetchone()['USERNAME'])
  57. Setting up a development environment
  58. ------------------------------------
  59. If you want to quickly try out the included examples, you can set up a
  60. local `virtualenv <https://virtualenv.pypa.io/en/latest/>`_ with all the
  61. necessary requirements::
  62. virtualenv e
  63. source e/bin/activate
  64. pip install -r requirements.txt
  65. python setup.py develop
  66. You can start a Phoenix QueryServer instance on http://localhost:8765 for testing by running
  67. the following command in the pohoenix-queryserver-parent directory::
  68. mvn clean verify -am -pl phoenix-queryserver-it -Dtest=foo \
  69. -Dit.test=QueryServerBasicsIT#startLocalPQS \
  70. -Ddo.not.randomize.pqs.port=true -Dstart.unsecure.pqs=true
  71. You can start a secure (https+kerberos) Phoenix QueryServer instance on https://localhost:8765
  72. for testing by running the following command in the phoenix-queryserver-parent directory::
  73. mvn clean verify -am -pl phoenix-queryserver-it -Dtest=foo \
  74. -Dit.test=SecureQueryServerPhoenixDBIT#startLocalPQS \
  75. -Ddo.not.randomize.pqs.port=true -Dstart.secure.pqs=true
  76. this will also create a shell script in phoenix-queryserver-it/target/krb_setup.sh, that you can use to set
  77. up the environment for the tests.
  78. If you want to use the library without installing the phoenixdb library, you can use
  79. the `PYTHONPATH` environment variable to point to the library directly::
  80. cd phoenix-queryserver-parent/python-phoenixdb
  81. python setup.py build
  82. cd ~/my_project
  83. PYTHONPATH=$PHOENIX_HOME/build/lib python my_app.py
  84. Don't forget to run flake8 on your changes.
  85. Running the test suite
  86. ----------------------
  87. The library comes with a test suite for testing Python DB API 2.0 compliance and
  88. various Phoenix-specific features. In order to run the test suite, you need a
  89. working Phoenix database and set the ``PHOENIXDB_TEST_DB_URL`` environment variable::
  90. export PHOENIXDB_TEST_DB_URL='http://localhost:8765/'
  91. tox
  92. If you use a secure PQS server, you can set the connection parameters via the following environment
  93. variables:
  94. - PHOENIXDB_TEST_DB_TRUSTSTORE
  95. - PHOENIXDB_TEST_DB_AUTHENTICATION
  96. - PHOENIXDB_TEST_DB_AVATICA_USER
  97. - PHOENIXDB_TEST_DB_AVATICA_PASSWORD
  98. Similarly, tox can be used to run the test suite against multiple Python versions::
  99. pyenv install 3.5.5
  100. pyenv install 3.6.4
  101. pyenv install 2.7.14
  102. pyenv global 2.7.14 3.5.5 3.6.4
  103. PHOENIXDB_TEST_DB_URL='http://localhost:8765' tox
  104. You can use tox and docker to run the tests on supported python versions without
  105. installing the environments locally::
  106. docker build -t toxtest .
  107. docker run --rm --add-host=host.docker.internal:host-gateway -v `pwd`:/src toxtest
  108. You can also run the test suite from maven as part of the Java build by setting the
  109. run.full.python.testsuite property. You DO NOT need to set the PHOENIXDB_* enviroment variables,
  110. maven will set them up for you. The output of the test run will be saved in
  111. phoenix-queryserver/phoenix-queryserver-it/target/python-stdout.log and python-stderr.log::
  112. mvn clean verify -Drun.full.python.testsuite=true
  113. Known issues
  114. ------------
  115. - TIME and DATE columns in Phoenix are stored as full timestamps with a millisecond accuracy,
  116. but the remote protocol only exposes the time (hour/minute/second) or date (year/month/day)
  117. parts of the columns. (`CALCITE-797 <https://issues.apache.org/jira/browse/CALCITE-797>`_, `CALCITE-798 <https://issues.apache.org/jira/browse/CALCITE-798>`_)
  118. - TIMESTAMP columns in Phoenix are stored with a nanosecond accuracy, but the remote protocol truncates them to milliseconds. (`CALCITE-796 <https://issues.apache.org/jira/browse/CALCITE-796>`_)
  119. SQLAlchemy feature support
  120. --------------------------
  121. SQLAlchemy has a wide breadth of API, ranging from basic SQL commands to object-relational mapping support.
  122. Today, python-phoenixdb only supports the following subset of the complete SQLAlchemy API:
  123. - `Textual SQL <https://docs.sqlalchemy.org/en/13/core/tutorial.html#using-textual-sql>`_
  124. All other API should be considered not implemented.