Merge branch 'main' into update-tests-for-local

Author: PGijsbers

.github/PULL_REQUEST_TEMPLATE.md

@@ -5,7 +5,7 @@ the contribution guidelines: https://github.com/openml/openml-python/blob/main/C
 Please make sure that:
 
 * the title of the pull request is descriptive
-* this pull requests is against the `develop` branch
+* this pull requests is against the `main` branch
 * for any new functionality, consider adding a relevant example
 * add unit tests for new functionalities
     * collect files uploaded to test server using _mark_entity_for_removal()

CONTRIBUTING.md

@@ -44,7 +44,7 @@ To contribute to the openml-python package, follow these steps:
 
 0. Determine how you want to contribute (see above).
 1. Set up your local development environment.
-   1. Fork and clone the `openml-python` repository. Then, create a new branch from the ``develop`` branch. If you are new to `git`, see our [detailed documentation](#basic-git-workflow), or rely on your favorite IDE.   
+   1. Fork and clone the `openml-python` repository. Then, create a new branch from the ``main`` branch. If you are new to `git`, see our [detailed documentation](#basic-git-workflow), or rely on your favorite IDE.   
    2. [Install the local dependencies](#install-local-dependencies) to run the tests for your contribution.
    3. [Test your installation](#testing-your-installation) to ensure everything is set up correctly.
 4. Implement your contribution. If contributing to the documentation, see [here](#contributing-to-the-documentation).
@@ -91,7 +91,7 @@ pytest tests/test_datasets/test_dataset.py::OpenMLDatasetTest
 pytest tests/test_datasets/test_dataset.py::OpenMLDatasetTest::test_get_data
 ```
 
-To test your new contribution, add [unit tests](https://github.com/openml/openml-python/tree/develop/tests), and, if needed, [examples](https://github.com/openml/openml-python/tree/develop/examples) for any new functionality being introduced. Some notes on unit tests and examples:
+To test your new contribution, add [unit tests](https://github.com/openml/openml-python/tree/main/tests), and, if needed, [examples](https://github.com/openml/openml-python/tree/main/examples) for any new functionality being introduced. Some notes on unit tests and examples:
 * If a unit test contains an upload to the test server, please ensure that it is followed by a file collection for deletion, to prevent the test server from bulking up. For example, `TestBase._mark_entity_for_removal('data', dataset.dataset_id)`, `TestBase._mark_entity_for_removal('flow', (flow.flow_id, flow.name))`.
 * Please ensure that the example is run on the test server by beginning with the call to `openml.config.start_using_configuration_for_example()`, which is done by default for tests derived from `TestBase`.
 * Add the `@pytest.mark.sklearn` marker to your unit tests if they have a dependency on scikit-learn.
@@ -109,7 +109,7 @@ export OPENML_TEST_SERVER_ADMIN_KEY="admin-key"
 
 ### Pull Request Checklist
 
-You can go to the `openml-python` GitHub repository to create the pull request by [comparing the branch](https://github.com/openml/openml-python/compare) from your fork with the `develop` branch of the `openml-python` repository. When creating a pull request, make sure to follow the comments and structured provided by the template on GitHub.
+You can go to the `openml-python` GitHub repository to create the pull request by [comparing the branch](https://github.com/openml/openml-python/compare) from your fork with the `main` branch of the `openml-python` repository. When creating a pull request, make sure to follow the comments and structured provided by the template on GitHub.
 
 **An incomplete contribution** -- where you expect to do more work before
 receiving a full review -- should be submitted as a `draft`. These may be useful
@@ -127,7 +127,7 @@ in the PR description.
 
 The preferred workflow for contributing to openml-python is to
 fork the [main repository](https://github.com/openml/openml-python) on
-GitHub, clone, check out the branch `develop`, and develop on a new branch
+GitHub, clone, check out the branch `main`, and develop on a new branch
 branch. Steps:
 
 0. Make sure you have git installed, and a GitHub account.
@@ -148,7 +148,7 @@ local disk:
 3. Switch to the ``develop`` branch:
 
    ```bash
-   git checkout develop
+   git checkout main
    ```
 
 3. Create a ``feature`` branch to hold your development changes:
@@ -157,7 +157,7 @@ local disk:
    git checkout -b feature/my-feature
    ```
 
-   Always use a ``feature`` branch. It's good practice to never work on the ``main`` or ``develop`` branch! 
+   Always use a ``feature`` branch. It's good practice to never work on the ``main`` branch! 
    To make the nature of your pull request easily visible, please prepend the name of the branch with the type of changes you want to merge, such as ``feature`` if it contains a new feature, ``fix`` for a bugfix, ``doc`` for documentation and ``maint`` for other maintenance on the package.
 
 4. Develop the feature on your feature branch. Add changed files using ``git add`` and then ``git commit`` files:

README.md

@@ -20,7 +20,7 @@
 [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
 <!-- Add green badges for CI and precommit -->
 
-[Installation](https://openml.github.io/openml-python/main/#how-to-get-openml-for-python) | [Documentation](https://openml.github.io/openml-python) | [Contribution guidelines](https://github.com/openml/openml-python/blob/develop/CONTRIBUTING.md)
+[Installation](https://openml.github.io/openml-python/main/#how-to-get-openml-for-python) | [Documentation](https://openml.github.io/openml-python) | [Contribution guidelines](https://github.com/openml/openml-python/blob/main/CONTRIBUTING.md)
 </div>
 
 OpenML-Python provides an easy-to-use and straightforward Python interface for [OpenML](http://openml.org), an online platform for open science collaboration in machine learning.
@@ -94,7 +94,7 @@ Bibtex entry:
 We welcome contributions from both new and experienced developers!
 
 If you would like to contribute to OpenML-Python, please read our  
-[Contribution Guidelines](https://github.com/openml/openml-python/blob/develop/CONTRIBUTING.md).
+[Contribution Guidelines](https://github.com/openml/openml-python/blob/main/CONTRIBUTING.md).
 
 If you are new to open-source development, a great way to get started is by
 looking at issues labeled **"good first issue"** in our GitHub issue tracker.

docs/developer_setup.md

@@ -0,0 +1,210 @@
+# OpenML Local Development Environment Setup
+
+This guide outlines the standard procedures for setting up a local development environment for the OpenML ecosystem. It covers the configuration of the backend servers (API v1 and API v2) and the Python Client SDK.
+
+OpenML currently has two backend architecture:
+
+* **API v1**: The PHP-based server currently serving production traffic.
+* **API v2**: The Python-based server (FastAPI) currently under active development.
+
+> Note on Migration: API v1 is projected to remain operational through at least 2026. API v2 is the target architecture for future development.
+
+## 1. API v1 Setup (PHP Backend)
+
+This section details the deployment of the legacy PHP backend.
+
+### Prerequisites
+
+* **Docker**: Docker Desktop (Ensure the daemon is running).
+* **Version Control**: Git.
+
+### Installation Steps
+
+#### 1. Clone the Repository
+
+Retrieve the OpenML services source code:
+
+```bash
+git clone https://github.com/openml/services
+cd services
+```
+
+#### 2. Configure File Permissions
+
+To ensure the containerized PHP service can write to the local filesystem, initialize the data directory permissions.
+
+From the repository root:
+
+```bash
+chown -R www-data:www-data data/php
+```
+
+If the `www-data` user does not exist on the host system, grant full permissions as a fallback:
+
+```bash
+chmod -R 777 data/php
+```
+
+#### 3. Launch Services
+
+Initialize the container stack:
+
+```bash
+docker compose --profile all up -d
+```
+
+#### Warning: Container Conflicts
+
+If API v2 (Python backend) containers are present on the system, name conflicts may occur. To resolve this, stop and remove existing containers before launching API v1:
+
+```bash
+docker compose --profile all down
+docker compose --profile all up -d
+```
+
+#### 4. Verification
+
+Validate the deployment by accessing the flow endpoint. A successful response will return structured JSON data.
+
+* **Endpoint**: http://localhost:8080/api/v1/json/flow/181
+
+### Client Configuration
+
+To direct the `openml-python` client to the local API v1 instance, modify the configuration as shown below. The API key corresponds to the default key located in `services/config/php/.env`.
+
+```python
+import openml
+from openml_sklearn.extension import SklearnExtension
+from sklearn.neighbors import KNeighborsClassifier
+
+# Configure client to use local Docker instance
+openml.config.server = "http://localhost:8080/api/v1/xml"
+openml.config.apikey = "AD000000000000000000000000000000"
+
+# Test flow publication
+clf = KNeighborsClassifier(n_neighbors=3)
+extension = SklearnExtension()
+knn_flow = extension.model_to_flow(clf)
+
+knn_flow.publish()
+```
+
+## 2. API v2 Setup (Python Backend)
+
+This section details the deployment of the FastAPI backend.
+
+### Prerequisites
+
+* **Docker**: Docker Desktop (Ensure the daemon is running).
+* **Version Control**: Git.
+
+### Installation Steps
+
+#### 1. Clone the Repository
+
+Retrieve the API v2 source code:
+
+```bash
+git clone https://github.com/openml/server-api
+cd server-api
+```
+
+#### 2. Launch Services
+
+Build and start the container stack:
+
+```bash
+docker compose --profile all up
+```
+
+#### 3. Verification
+
+Validate the deployment using the following endpoints:
+
+* **Task Endpoint**: http://localhost:8001/tasks/31
+* **Swagger UI (Documentation)**: http://localhost:8001/docs
+
+## 3. Python SDK (`openml-python`) Setup
+
+This section outlines the environment setup for contributing to the OpenML Python client.
+
+### Installation Steps
+
+#### 1. Clone the Repository
+
+```bash
+git clone https://github.com/openml/openml-python
+cd openml-python
+```
+
+#### 2. Environment Initialization
+
+Create an isolated virtual environment (example using Conda):
+
+```bash
+conda create -n openml-python-dev python=3.12
+conda activate openml-python-dev
+```
+
+#### 3. Install Dependencies
+
+Install the package in editable mode, including development and documentation dependencies:
+
+```bash
+python -m pip install -e ".[dev,docs]"
+```
+
+#### 4. Configure Quality Gates
+
+Install pre-commit hooks to enforce coding standards:
+
+```bash
+pre-commit install
+pre-commit run --all-files
+```
+
+## 4. Testing Guidelines
+
+The OpenML Python SDK utilizes `pytest` markers to categorize tests based on dependencies and execution context.
+
+| Marker            | Description                                                                 |
+|-------------------|-----------------------------------------------------------------------------|
+| `sklearn`          | Tests requiring `scikit-learn`. Skipped if the library is missing.          |
+| `production`      | Tests that interact with the live OpenML server (real API calls).         |
+| `uses_test_server`  | Tests requiring the OpenML test server environment.                       |
+
+### Execution Examples
+
+Run the full test suite:
+
+```bash
+pytest
+```
+
+Run a specific subset (e.g., `scikit-learn` tests):
+
+```bash
+pytest -m sklearn
+```
+
+Exclude production tests (local only):
+
+```bash
+pytest -m "not production"
+```
+
+### Admin Privilege Tests
+
+Certain tests require administrative privileges on the test server. These are skipped automatically unless an admin API key is provided via environment variables.
+
+#### Windows (PowerShell):
+
+```shell
+$env:OPENML_TEST_SERVER_ADMIN_KEY = "admin-key"
+```
+
+#### Linux/macOS:
+
+```bash
+export OPENML_TEST_SERVER_ADMIN_KEY="admin-key"
+```

mkdocs.yml

@@ -65,6 +65,7 @@ nav:
   - Advanced User Guide: details.md
   - API: reference/
   - Contributing: contributing.md
+  - Developer Setup: developer_setup.md
 
 markdown_extensions:
   - pymdownx.highlight:

openml/utils/__init__.py

@@ -0,0 +1,39 @@
+"""Utilities module."""
+
+from openml.utils._openml import (
+    ProgressBar,
+    ReprMixin,
+    _create_cache_directory,
+    _create_cache_directory_for_id,
+    _create_lockfiles_dir,
+    _delete_entity,
+    _get_cache_dir_for_id,
+    _get_cache_dir_for_key,
+    _get_rest_api_type_alias,
+    _list_all,
+    _remove_cache_dir_for_id,
+    _tag_entity,
+    _tag_openml_base,
+    extract_xml_tags,
+    get_cache_size,
+    thread_safe_if_oslo_installed,
+)
+
+__all__ = [
+    "ProgressBar",
+    "ReprMixin",
+    "_create_cache_directory",
+    "_create_cache_directory_for_id",
+    "_create_lockfiles_dir",
+    "_delete_entity",
+    "_get_cache_dir_for_id",
+    "_get_cache_dir_for_key",
+    "_get_rest_api_type_alias",
+    "_list_all",
+    "_remove_cache_dir_for_id",
+    "_tag_entity",
+    "_tag_openml_base",
+    "extract_xml_tags",
+    "get_cache_size",
+    "thread_safe_if_oslo_installed",
+]

openml/utils.py openml/utils/_openml.pyopenml/utils.py renamed to openml/utils/_openml.py

@@ -26,8 +26,7 @@
 import openml
 import openml._api_calls
 import openml.exceptions
-
-from . import config
+from openml import config
 
 # Avoid import cycles: https://mypy.readthedocs.io/en/latest/common_issues.html#import-cycles
 if TYPE_CHECKING:
@@ -436,6 +435,18 @@ def safe_func(*args: P.args, **kwargs: P.kwargs) -> R:
         return func
 
 
+def get_cache_size() -> int:
+    """Calculate the size of OpenML cache directory
+
+    Returns
+    -------
+    cache_size: int
+        Total size of cache in bytes
+    """
+    path = Path(config.get_cache_directory())
+    return sum(f.stat().st_size for f in path.rglob("*") if f.is_file())
+
+
 def _create_lockfiles_dir() -> Path:
     path = Path(config.get_cache_directory()) / "locks"
     # TODO(eddiebergman): Not sure why this is allowed to error and ignore???