Skip to content

Latest commit

 

History

History
108 lines (73 loc) · 4.72 KB

CONTRIBUTING.md

File metadata and controls

108 lines (73 loc) · 4.72 KB

To try this out locally:

  • Use Python 3.9 or higher; pyenv is recommended for installing and managing Python versions.
  • Install poetry
  • python -m venv .venv to create a virtual environment.
  • source .venv/bin/activate to use that virtual environment.
  • poetry install to install project dependencies.

VSCode is recommended for development.

  • For formatting, the project uses the Black code formatter, and the Black Formatter VSCode extension is recommended.
  • For linting, the project uses the Flake8 linter and the Flake8 extension is recommended. These tools are included in the project by pyproject.toml and the settings are in .vscode/settings.json.

You can also get additional information at these instructions for getting setup in VSCode with linting and formatting enabled.

Running the tests

Before running any tests, first deploy the test application:

  • Use Java 8 or higher
  • cd test-app
  • Create a file named gradle-local.properties and add mlPassword= to it, with the value of the property being your admin user's password.
  • Verify that the host/port/username in gradle.properties work for your MarkLogic installation.
  • Run ./gradlew -i mlDeploy
  • cd ..

Then run all the tests:

pytest

To run an individual test:

pytest tests/test_search.py

To run an individual test method:

pytest test/test_search.py::test_search

Note that due to the pytest config in the pyproject.toml file, all Python logging should appear immediately as tests are executed. If you are using VSCode, you can see the logging by selecting "Python Test Log" in the "Output" panel.

Testing the client in a Python shell

After running poetry install as described above, you can start a Python shell and manually test the client. You will need to launch the shell in the same Python virtual environment as the one in which you ran poetry install. After ensuring you've done that, start a new Python shell by running python.

You can then import the client via:

from marklogic import Client

You can instantiate an instance of the client that communicates with this project's test application via:

client = Client("http://localhost:8030", digest=("python-test-user", "password"))

And you can then start sending requests with the client - for example:

r = client.get("/v1/search?format=json&pageLength=2")
r.json()

You can also use the scripts in the ./shell directory to initialize a client. The following initializes a client that connects to this project's test application:

python -i shell/test_app.py

And this initializes a client that connects to the OOTB App-Services app server, which is used for examples in this project's documentation:

python -i shell/docs.py

Testing updates in a different local project

If you are using this in another project and making changes for it, use the following command to make the changes to this local project immediately reflected in a dependent project: poetry add <local-path-to-this-project>/marklogic-python-client/

Using this method will allow you to very easily test changes to this project, in a different local project.

Keep in mind that you probably do not want to check that version of the pyproject.toml file into version control since it is only useful locally.

Testing the documentation locally

The docs for this project are stored in the ./docs directory as a set of Markdown files. These are published via GitHub Pages using the configuration found under "Settings / Pages" in this repository.

You can build and test the docs locally by following these GitHub instructions, though you don't need to perform all of those steps since some of the files generated by doing so are already in the ./docs directory. You just need to do the following:

  1. Install the latest Ruby (rbenv works well for this).
  2. Install Jekyll.
  3. Go to the docs directory - cd ./docs .
  4. Run bundle install (this may not be necessary due to Gemfile.lock being in version control).
  5. Run bundle exec jekyll serve.

You can then go to http://localhost:4000 to view the docs.