Finished documenting code and small update to README.md

Author: maksymuimanov

README.md

@@ -7,7 +7,7 @@
 [![Java: 17+](https://img.shields.io/badge/Java-17%2B-blue.svg)](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html)
 [![Spring Boot: 3.5.3+](https://img.shields.io/badge/Spring%20Boot-3.5.3%2B-brightgreen.svg)](https://spring.io/projects/spring-boot)
 [![Python: 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
-![Tests Passed: 80%](https://img.shields.io/badge/Tests%20Passed-80%25-green.svg)
+![Tests Passed: 90%](https://img.shields.io/badge/Tests%20Passed-80%25-green.svg)
 
 <hr>
 
@@ -17,6 +17,7 @@
 - [Introduction](#-introduction)
 - [Features & Architecture](#-features--architecture)
   - [Core Components](#core-components)
+  - [Architecture Diagram](#architecture-diagram)
   - [Security](#security)
   - [Cache](#cache)
 - [Installation and Setup](#-installation-and-setup)
@@ -76,64 +77,86 @@ Spring Boot Python Executor provides a flexible architecture for executing Pytho
   - Result resolution for capturing Python output
 - **PythonProcessor**: Connects resolvers and executors
 
+### Architecture Diagram
+
+If you are willing to use AOP based script processing, 
+your Python code will move from Python annotation to a configured PythonProcessor implementation object
+
 ```mermaid
 ---
-title: Basic Python script flow
+title: Python annotations flow
 ---
 
 classDiagram
-  PythonBefore --> PythonProcessor: Annotation @PythonBefore forwards the script to the PythonProcessor implementation
-  PythonAfter --> PythonProcessor: Annotation @PythonAfter forwards the script to the PythonProcessor implementation
-  PythonProcessor --> PythonFileHandler: Firstly, the script is checked whether it's a .py file or String script
-  PythonProcessor <-- PythonFileHandler: If it's a file, the content is read as a String value and returned
-  PythonProcessor --> PythonResolverHolder: Secondly, the script may be  transformed by multiple PythonResolver implementations. You can configure declared implementations by using spring.python.resolver.declared property
-  PythonProcessor <-- PythonResolverHolder: Returns resolved script from multiple PythonResolvers
-  PythonProcessor --> PythonExecutor: Finally, the script is executed by PythonExecutor implementation. You can choose needed implementation by configuring the property named spring.python.executor.type
-  PythonProcessor <-- PythonExecutor: The method returns null, because of annotation usage, but if you would like to get specific result object you need to call process(...) function manually 
-  
-  class PythonBefore {
-      +String value()
-      +String script()
-      +String[] activeProfiles()
-  }
-  
-  class PythonAfter {
-      +String value()
-      +String script()
-      +String[] activeProfiles()
-  }
-  
-  class PythonProcessor {
-    <<interface>>
-    +R process(String script, Class<? extends R> resultClass, Map<String, Object> arguments)
-  }
-  
-  class PythonFileHandler {
-    <<interface>>
-    +boolean isPythonFile(String path)
-    +void writeScriptBodyToFile(String path, String script)
-    +void writeScriptBodyToFile(Path path, String script)
-    +String readScriptBodyFromFile(String path)
-    +String readScriptBodyFromFile(Path path)
-    +String readScriptBodyFromFile(String path, UnaryOperator<String> mapper)
-    +String readScriptBodyFromFile(Path path, UnaryOperator<String> mapper)
-    +Path getScriptPath(String path)
-  }
-  
-  class PythonResolverHolder {
-    <<interface>>
-    +Iterator<PythonResolver> iterator()
-    +void forEach(Consumer<? super PythonResolver> action)
-    +Spliterator<PythonResolver> spliterator()
-    +Stream<PythonResolver> stream()
-    +String resolveAll(String script, Map<String, Object> arguments);
-    +List<PythonResolver> getResolvers();
-  }
-  
-  class PythonExecutor {
-    <<interface>>
-    +R execute(String script, Class<? extends R> resultClass)
-  }
+    PythonBefores --> PythonAnnotationEvaluator
+    PythonBefore --> PythonAnnotationEvaluator
+    PythonAfters --> PythonAnnotationEvaluator
+    PythonAfter --> PythonAnnotationEvaluator
+    PythonAnnotationEvaluator --> PythonAnnotationValueCompounder
+    PythonAnnotationEvaluator <-- PythonAnnotationValueCompounder
+    PythonAnnotationEvaluator --> ProfileChecker
+    PythonAnnotationEvaluator <-- ProfileChecker
+    PythonAnnotationEvaluator --> PythonArgumentsExtractor
+    PythonAnnotationEvaluator <-- PythonArgumentsExtractor
+    PythonAnnotationEvaluator --> PythonProcessor
+    PythonAnnotationValueCompounder --> PythonAnnotationValueExtractor
+    PythonAnnotationValueCompounder <-- PythonAnnotationValueExtractor
+    PythonAnnotationValueExtractor --> PythonMethodExtractor
+    PythonAnnotationValueExtractor <-- PythonMethodExtractor
+    PythonArgumentsExtractor --> PythonMethodExtractor
+    PythonArgumentsExtractor <-- PythonMethodExtractor
+    
+    
+```
+
+Also, you can use only PythonProcessor object to execute Python code:
+```mermaid
+---
+title: PythonProcessor flow
+---
+
+classDiagram
+    PythonProcessor --> PythonFileHandler: Firstly, the script is checked whether it's a .py file or String script
+    PythonProcessor <-- PythonFileHandler: If it's a file, the content is read as a String value and returned
+    PythonProcessor --> PythonResolverHolder: Secondly, the script may be  transformed by multiple PythonResolver implementations. You can configure declared implementations by using spring.python.resolver.declared property
+    PythonProcessor <-- PythonResolverHolder: Returns resolved script from multiple PythonResolvers
+    PythonProcessor --> PythonExecutor: Finally, the script is executed by PythonExecutor implementation. You can choose needed implementation by configuring the property named spring.python.executor.type
+    PythonProcessor <-- PythonExecutor: The method returns null, because of annotation usage, but if you would like to get specific result object you need to call process(...) function manually
+    
+    class PythonProcessor {
+        <<interface>>
+        +void process(String script)
+        +void process(String script, Map<String, Object> arguments)
+        +R process(String script, Class<? extends R> resultClass)
+        +R process(String script, Class<? extends R> resultClass, Map<String, Object> arguments)
+    }
+    
+    class PythonFileHandler {
+        <<interface>>
+        +boolean isPythonFile(String path)
+        +void writeScriptBodyToFile(String path, String script)
+        +void writeScriptBodyToFile(Path path, String script)
+        +String readScriptBodyFromFile(String path)
+        +String readScriptBodyFromFile(Path path)
+        +String readScriptBodyFromFile(String path, UnaryOperator<String> mapper)
+        +String readScriptBodyFromFile(Path path, UnaryOperator<String> mapper)
+        +Path getScriptPath(String path)
+    }
+    
+    class PythonResolverHolder {
+        <<interface>>
+        +Iterator<PythonResolver> iterator()
+        +void forEach(Consumer<? super PythonResolver> action)
+        +Spliterator<PythonResolver> spliterator()
+        +Stream<PythonResolver> stream()
+        +String resolveAll(String script, Map<String, Object> arguments);
+        +List<PythonResolver> getResolvers();
+    }
+    
+    class PythonExecutor {
+        <<interface>>
+        +R execute(String script, Class<? extends R> resultClass)
+    }
 ```
 
 ### Security

demo-app/pom.xml

@@ -25,6 +25,10 @@
             <groupId>io.github.w4t3rcs</groupId>
             <artifactId>spring-boot-python-executor-cache-starter</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.github.w4t3rcs</groupId>
+            <artifactId>spring-boot-python-executor-testcontainers</artifactId>
+        </dependency>
 
         <dependency>
             <groupId>org.springframework.boot</groupId>

demo-app/src/test/java/io/w4t3rcs/demo/DemoAppApplicationTests.java

@@ -0,0 +1,22 @@
+package io.w4t3rcs.demo;
+
+import io.w4t3rcs.demo.dto.MLScriptRequest;
+import io.w4t3rcs.demo.service.PythonService;
+import org.junit.jupiter.api.Test;
+import org.mockito.Mockito;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.context.annotation.Import;
+
+@SpringBootTest
+@Import(TestcontainersConfiguration.class)
+public class PythonServiceTests {
+    @Autowired
+    private PythonService pythonService;
+
+    @Test
+    public void doExecuteWithPython() {
+        MLScriptRequest request = Mockito.mock(MLScriptRequest.class);
+        pythonService.doSomethingWithPythonInside(request);
+    }
+}

demo-app/src/test/java/io/w4t3rcs/demo/PythonServiceTests.java

@@ -1,8 +1,18 @@
 package io.w4t3rcs.demo;
 
+import io.w4t3rcs.python.PythonGrpcServerContainer;
 import org.springframework.boot.test.context.TestConfiguration;
+import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
+import org.springframework.context.annotation.Bean;
 
 @TestConfiguration(proxyBeanMethods = false)
 class TestcontainersConfiguration {
-
+    @Bean
+    @ServiceConnection
+    PythonGrpcServerContainer pythonGrpcServerContainer() {
+        return new PythonGrpcServerContainer("w4t3rcs/spring-boot-python-executor-python-grpc-server")
+                .withUsername("user")
+                .withPassword("pass")
+                .withAdditionalImports(new String[]{"scikit-learn", "numpy", "pandas"});
+    }
 }

demo-app/src/test/java/io/w4t3rcs/demo/TestDemoAppApplication.java

@@ -6,16 +6,63 @@
 
 import java.time.Duration;
 
+/**
+ * Container for running a Python gRPC server inside a Docker container.
+ * <p>
+ * Extends {@link PythonServerContainer} to provide configuration specific
+ * to the Python gRPC server implementation used in the Docker image
+ * {@code w4t3rcs/spring-boot-python-executor-python-grpc-server}.
+ * <p>
+ * The container exposes the standard gRPC port {@code 50051} and waits
+ * for both the port availability and a specific log message indicating
+ * successful startup.
+ *
+ * <pre>{@code
+ * try (PythonGrpcServerContainer grpcServerContainer = new PythonGrpcServerContainer("w4t3rcs/spring-boot-python-executor-python-grpc-server:latest")
+ *         .withUsername("user")
+ *         .withPassword("pass")) {
+ *     grpcServerContainer.start();
+ *
+ *     //Do something after the container has been started
+ * }
+ * }</pre>
+ *
+ * @see PythonServerContainer
+ * @see PythonRestServerContainer
+ * @author w4t3rcs
+ * @since 1.0.0
+ */
 public class PythonGrpcServerContainer extends PythonServerContainer<PythonGrpcServerContainer> {
     public static final String PYTHON_SERVER_THREAD_POOL_MAX_WORKERS_ENV = "PYTHON_SERVER_THREAD_POOL_MAX_WORKERS";
     private static final DockerImageName DOCKER_IMAGE_NAME = DockerImageName.parse("w4t3rcs/spring-boot-python-executor-python-grpc-server");
     private static final int SERVER_DEFAULT_PORT = 50051;
-    public static final String GRPC_SERVER_RUNNING_MESSAGE = ".*gRPC server running.+";
+    private static final String GRPC_SERVER_RUNNING_MESSAGE = ".*gRPC server running.+";
 
+    /**
+     * Creates a new {@link PythonGrpcServerContainer} instance with the given Docker image name.
+     * <p>
+     * The provided image name must be compatible with
+     * {@code w4t3rcs/spring-boot-python-executor-python-grpc-server}.
+     *
+     * @param image non-null Docker image name string, must be compatible with the expected base image
+     */
     public PythonGrpcServerContainer(String image) {
         this(DockerImageName.parse(image));
     }
 
+    /**
+     * Creates a new {@link PythonGrpcServerContainer} instance with the given {@link DockerImageName}.
+     * <p>
+     * The provided Docker image must be compatible with
+     * {@code w4t3rcs/spring-boot-python-executor-python-grpc-server}.
+     * <p>
+     * The container exposes port {@value #SERVER_DEFAULT_PORT} and waits
+     * for the port to be listening as well as the log message defined by
+     * {@value #GRPC_SERVER_RUNNING_MESSAGE} before considering itself started.
+     * The startup timeout is 5 minutes.
+     *
+     * @param dockerImageName non-null {@link DockerImageName} instance, must be compatible with the expected base image
+     */
     public PythonGrpcServerContainer(DockerImageName dockerImageName) {
         super(dockerImageName);
         dockerImageName.assertCompatibleWith(DOCKER_IMAGE_NAME);
@@ -27,12 +74,29 @@ public PythonGrpcServerContainer(DockerImageName dockerImageName) {
                         .withStrategy(Wait.forLogMessage(GRPC_SERVER_RUNNING_MESSAGE, 1)));
     }
 
+    /**
+     * Sets the maximum number of workers for the thread pool in the Python gRPC server.
+     * <p>
+     * This value is passed as an environment variable
+     * {@value #PYTHON_SERVER_THREAD_POOL_MAX_WORKERS_ENV} to the container.
+     *
+     * @param maxWorkers non-negative integer specifying maximum thread pool workers, zero or negative values are accepted but their effect depends on server implementation
+     * @return this container instance for fluent chaining, never {@code null}
+     */
     public PythonGrpcServerContainer withThreadPoolMaxWorkers(int maxWorkers) {
         this.withEnv(PYTHON_SERVER_THREAD_POOL_MAX_WORKERS_ENV, String.valueOf(maxWorkers));
         return this.self();
     }
 
+    /**
+     * Returns the server URL in the form {@code host:port} where {@code host}
+     * is the container host and {@code port} is the mapped port {@value #SERVER_DEFAULT_PORT}.
+     * <p>
+     * This method should only be called after the container has been started.
+     *
+     * @return non-null, non-empty string representing the server URL, e.g. {@code localhost:50051}
+     */
     public String getServerUrl() {
         return this.getHost() + ":" + this.getMappedPort(SERVER_DEFAULT_PORT);
     }
-}
+}