Merge pull request #12 from Sh1nku/logging

Add logging

.github/workflows/generate_docs.yml

@@ -21,11 +21,11 @@ jobs:
           tar -xzf mdbook-v0.4.34-x86_64-unknown-linux-gnu.tar.gz
           mv mdbook /usr/local/bin
       - name: Build Rust documentation
-        working-directory: ./framework/docs
+        working-directory: ./docs
         run: |
           mdbook build
-          mkdir ../../docs
-          mv book/* ../../docs
+          mkdir docs_built
+          mv book/* docs_built
       - uses: actions/setup-python@v4
         with:
           python-version: 3.8
@@ -34,5 +34,5 @@ jobs:
         run: |
           pip install -r requirements-dev.txt
           ./generate_documentation.py
-          mkdir ../../docs/python
-          mv docs/* ../../docs/python
+          mkdir ../../docs/docs_built/python
+          mv docs/* ../../docs/docs_built/python

.github/workflows/publish_docs.yml

@@ -30,11 +30,11 @@ jobs:
           tar -xzf mdbook-v0.4.34-x86_64-unknown-linux-gnu.tar.gz
           mv mdbook /usr/local/bin
       - name: Build Rust documentation
-        working-directory: ./framework/docs
+        working-directory: ./docs
         run: |
           mdbook build
-          mkdir ../../docs
-          mv book/* ../../docs
+          mkdir docs_built
+          mv book/* docs_built
       - uses: actions/setup-python@v4
         with:
           python-version: 3.8
@@ -43,12 +43,12 @@ jobs:
         run: |
           pip install -r requirements-dev.txt
           ./generate_documentation.py
-          mkdir ../../docs/python
-          mv docs/* ../../docs/python
+          mkdir ../../docs/docs_built/python
+          mv docs/* ../../docs/docs_built/python
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v2
         with:
-          path: 'docs/'
+          path: 'docs/docs_built/'
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v2

.gitignore

@@ -1,2 +1,2 @@
 /target
-/Cargo.lock
+/Cargo.lock

CHANGELOG.md

@@ -1,36 +1,50 @@
+# v0.5.0
+
+* Add logging of solr requests
+
 # v0.4.3
+
 * Fix mypy not recognizing .pyi files
 * Add static type checking test for mypy and pyright
 
 # v0.4.2
+
 * Switch out openssl for rustls
 * Run publish CI when creating PRs
 
 # v0.4.1
-* Relax version requirements. 
+
+* Relax version requirements.
 * Add Python 3.12 to CI
 * Note: Not released to PyPi due to relying on openssl which could not run in manylinux
 
 # v0.4.0
+
 * Make authentication error into its own error, instead of Json decode error
 * Make inherited error types transparently pass through parent error
 
 # v0.3.2
+
 * `num_found_exact` was introduced in Solr 8.6. This caused deserialization to fail on older versions.
   Changed so that it will be emulated as `true` for older versions.
 
 # v0.3.1
+
 * Fix error in python documentation
 
 # v0.3.0
+
 * Add Facet sets
 * Add Json facets
-* Be more permissive with arguments to builders, using `Into<Option>`, `Into<String` and `IntoIterator` where appropriate
+* Be more permissive with arguments to builders, using `Into<Option>`, `Into<String` and `IntoIterator` where
+  appropriate
 * Rename builders removing `Builder` suffix
 
 # v0.2.0
+
 * Add query parsers (lucene, dismax, edismax)
 
 # v0.1.1
+
 * Fix error in rust setup documentation example
 * Add mdbook, and pydoc documentation

Cargo.toml

@@ -31,4 +31,7 @@ regex = "1"
 dotenv = "0.15"
 pyo3 = "0.21"
 pyo3-asyncio = { package = "pyo3-asyncio-0-21", version = "0.21" }
-pythonize = "0.21"
+pyo3-log = "0.10.0"
+pythonize = "0.21"
+env_logger = "0.11.3"
+serial_test = "3.1.1"

docs/.gitignore

@@ -0,0 +1,2 @@
+book
+docs_built

framework/docs/book.toml → docs/book.toml

@@ -4,3 +4,9 @@ language = "en"
 multilingual = false
 src = "src"
 title = "Solrstice Docs"
+
+[rust]
+edition = "2021"
+
+[preprocessor.inject_docstring]
+command = "python3 inject.py"

docs/inject.py

@@ -0,0 +1,38 @@
+#!/usr/bin/python3
+import copy
+import json
+import sys
+from typing import Any, Dict
+import re
+
+if __name__ == '__main__':
+    if len(sys.argv) > 1: # we check if we received any argument
+        if sys.argv[1] == "supports":
+            # then we are good to return an exit status code of 0, since the other argument will just be the renderer's name
+            sys.exit(0)
+
+    # load both the context and the book representations from stdin
+    context, book = json.load(sys.stdin)
+
+    # Inject files based on the following pattern: {{#inject_docstring ../tests/docs/create_client_test.rs}}
+    md_regex = re.compile(r'{{\s*#inject_docstring\s*(.*?)\s*}}')
+    # Inject docstrings from rust, eg
+    # ```rust,no_run
+    # use solrstice::Client;
+    # ```
+    rust_regex = re.compile(r'(```.*?```)', re.DOTALL)
+
+    for section in book['sections']:
+        chapter: Dict[str, Any] = section['Chapter']
+        content: str = chapter['content']
+        for match in md_regex.finditer(content):
+            path = match.group(1)
+            with open(path, 'r') as f:
+                file_content = f.read()
+                rust_docstring_match = rust_regex.search(file_content)
+                if not rust_docstring_match:
+                    raise Exception(f"Could not find rust docstring in {path}\n{file_content}")
+                rust_docstring = rust_docstring_match.group(1)
+                chapter['content'] = chapter['content'].replace(match.group(0), rust_docstring).replace("///", "")
+    # raise Exception(json.dumps(book, indent=2))
+    print(json.dumps(book))

docs/src/SUMMARY.md

@@ -0,0 +1,3 @@
+# Summary
+
+- [Introduction](index.md)

docs/src/index.md

@@ -0,0 +1,41 @@
+# Solrstice Docs
+
+## Introduction
+
+Solrstice is a library for interacting with an Apache Solr cluster
+Currently version `8` and `9` is supported.
+The library is written in Rust, and has a wrapper to Python. Both async and blocking are supported in both languages.
+### Rust
+You can install the library by putting this in your `Cargo.toml`
+```toml
+solrstice = { version = "0.5.0", features = ["blocking"] }
+```
+If the `blocking` feature is not provided, only async will work.
+* [Rust mdBook docs]()
+* [Rust api docs](https://docs.rs/solrstice/) on docs.rs
+### Python
+```bash
+pip install solrstice
+```
+* [Python docs](https://sh1nku.github.io/solrstice/python)
+
+## Getting started
+
+### Creating a client
+
+{{#inject_docstring ../framework/src/docs/create_client_test.rs}}
+
+### Creating a collection
+
+{{#inject_docstring ../framework/src/docs/create_collection_test.rs}}
+
+### Indexing data
+
+{{#inject_docstring ../framework/src/docs/index_data_test.rs}}
+
+### Selecting data
+{{#inject_docstring ../framework/src/docs/select_data_test.rs}}
+
+### Deleting data
+
+{{#inject_docstring ../framework/src/docs/delete_data_test.rs}}

framework/Cargo.toml

@@ -32,4 +32,6 @@ blocking = ["tokio"]
 
 [dev-dependencies]
 tokio = { features = ["macros", "rt", "rt-multi-thread"], workspace = true }
+serial_test.workspace = true
 dotenv.workspace = true
+env_logger.workspace = true

framework/src/clients/blocking_cloud_client.rs

@@ -180,7 +180,7 @@ impl BlockingSolrCloudClient {
     /// # Ok(())
     /// # }
     /// ```
-    pub fn collection_exists<'a, S: AsRef<str>>(&self, name: S) -> Result<bool, SolrError> {
+    pub fn collection_exists<S: AsRef<str>>(&self, name: S) -> Result<bool, SolrError> {
         collection_exists_blocking(&self.context, name)
     }
 

framework/src/docs/create_client_test.rs

@@ -0,0 +1,10 @@
+use serial_test::parallel;
+
+/// ```rust
+/// # use solrstice::clients::async_cloud_client::AsyncSolrCloudClient;
+/// # use solrstice::hosts::solr_server_host::SolrSingleServerHost;
+/// # use solrstice::models::context::SolrServerContextBuilder;
+/// let context = SolrServerContextBuilder::new(SolrSingleServerHost::new("http://localhost:8983")).build();
+/// let client = AsyncSolrCloudClient::new(context);
+/// ```
+async fn create_client_test() {}

framework/src/docs/create_collection_test.rs

@@ -0,0 +1,20 @@
+use serial_test::parallel;
+
+/// ```rust,no_run
+/// # use solrstice::clients::async_cloud_client::AsyncSolrCloudClient;
+/// # use solrstice::hosts::solr_server_host::SolrSingleServerHost;
+/// # use solrstice::models::context::SolrServerContextBuilder;
+/// # use std::path::Path;
+/// # async fn run() -> Result<(), Box<dyn std::error::Error>> {
+/// # let context = SolrServerContextBuilder::new(SolrSingleServerHost::new("")).build();
+/// # let client = AsyncSolrCloudClient::new(context);
+/// client
+///    .upload_config("example_config", Path::new("/path/to/config"))
+///    .await?;
+/// client
+///    .create_collection("example_collection", "example_config", 1, 1)
+///    .await?;
+///     # Ok(())
+///  # }
+/// ```
+async fn create_collection_test() {}

framework/src/docs/delete_data_test.rs

@@ -0,0 +1,20 @@
+use serial_test::parallel;
+
+/// ```rust,no_run
+/// # use solrstice::clients::async_cloud_client::AsyncSolrCloudClient;
+/// # use solrstice::hosts::solr_server_host::SolrSingleServerHost;
+/// # use solrstice::models::context::SolrServerContextBuilder;
+/// # use solrstice::queries::index::DeleteQuery;
+/// # async fn run() -> Result<(), Box<dyn std::error::Error>> {
+/// # let context = SolrServerContextBuilder::new(SolrSingleServerHost::new("http://localhost:8983")).build();
+/// # let client = AsyncSolrCloudClient::new(context);
+/// client
+///     .delete(
+///         &DeleteQuery::new().ids(["example_document"]),
+///         "example_collection",
+///     )
+/// .await?;
+/// # Ok(())
+/// # }
+/// ```
+async fn delete_data_test() {}

framework/src/docs/index_data_test.rs

@@ -0,0 +1,27 @@
+use serial_test::parallel;
+
+/// ```rust,no_run
+/// # use solrstice::clients::async_cloud_client::AsyncSolrCloudClient;
+/// # use solrstice::hosts::solr_server_host::SolrSingleServerHost;
+/// # use solrstice::models::context::SolrServerContextBuilder;
+/// # use solrstice::queries::index::UpdateQuery;
+/// # use serde::{Serialize, Deserialize};
+///
+/// #[derive(Serialize, Deserialize, Debug)]
+/// struct TestData {
+///     id: String,
+/// }
+/// # async fn run() -> Result<(), Box<dyn std::error::Error>> {
+/// let docs = vec![TestData {
+///     id: "example_document".to_string(),
+/// }];
+///
+/// # let context = SolrServerContextBuilder::new(SolrSingleServerHost::new("")).build();
+/// # let client = AsyncSolrCloudClient::new(context);
+/// client
+///     .index(&UpdateQuery::new(), "example_collection", docs.as_slice())
+///     .await?;
+/// # Ok(())
+/// # }
+/// ```
+async fn index_data_test() {}