### Install Development Tools

Source: https://github.com/cubewise-code/tm1py/blob/master/docs/how-to-contribute.md

Install essential development tools such as Black for code formatting, Ruff for linting, and Pytest for testing.

```bash
pip install black ruff pytest
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/cubewise-code/tm1py/blob/master/docs/README.md

Install the necessary Python packages for developing and testing TM1py documentation.

```bash
pip install -e .[dev]
pip install -r docs/requirements-docs.txt
```

--------------------------------

### Nightly Release Workflow Example

Source: https://github.com/cubewise-code/tm1py/blob/master/docs/how-to-contribute.md

This example illustrates the daily release cycle, showing how merged PRs with different labels (or no label) affect the automated nightly build, release, and deployment process.

```text
Day 1:
  10:00 AM - PR #123 (bug fix, labeled 'release:patch') merged
  2:00 PM  - PR #124 (feature, labeled 'release:minor') merged
  5:00 PM  - PR #125 (docs update, no label) merged

  4:00 AM (next day) - Nightly workflow starts:
    - Runs full integration tests (2-3 hours)
    - If tests pass:
      → Creates release 2.2.0 (because of the minor label)
      → Publishes to PyPI (includes all 3 PRs)
      → Updates documentation
  7:00 AM - Users can: pip install --upgrade TM1py

Day 2:
  11:00 AM - PR #126 (minor fix, no label) merged
  3:00 PM  - PR #127 (test update, no label) merged

  4:00 AM (next day) - Nightly workflow starts:
    - No release labels found
    - Skips release (no version bump, no PyPI publish)
```

--------------------------------

### Install TM1py with Development Dependencies

Source: https://github.com/cubewise-code/tm1py/blob/master/Tests/_readme.md

Install TM1py along with development dependencies required for testing. Ensure you have a TM1 development environment set up.

```bash
pip install "tm1py[dev]"
```

--------------------------------

### Sample JSON for tm1-11-onprem TM1_CONNECTION

Source: https://github.com/cubewise-code/tm1py/blob/master/Tests/_gh_README.md

Example JSON structure for the TM1_CONNECTION variable for an on-premises TM1 11 environment.

```json
{
  "address": "localhost",
  "port": "8001",
  "user": "admin",
  "ssl": "true",
  "session_context": "gh_unittest"
}
```

--------------------------------

### Install TM1py

Source: https://github.com/cubewise-code/tm1py/blob/master/docs/getting-started.md

Install TM1py using pip. For pandas dataframe support, install with the 'pandas' extra.

```bash
pip install TM1py
```

```bash
pip install "tm1py[pandas]"
```

--------------------------------

### Sample JSON for tm1-11-cloud TM1_CONNECTION

Source: https://github.com/cubewise-code/tm1py/blob/master/Tests/_gh_README.md

Example JSON structure for the TM1_CONNECTION variable for a cloud-hosted TM1 11 environment.

```json
{
  "base_url": "https://server.planning-analytics.ibmcloud.com/tm1/api/tm1",
  "user": "server01_tm1_automation",
  "namespace": "LDAP",
  "ssl": true,
  "verify": true,
  "async_requests_mode": true,
  "session_context": "gh_unittest"
}
```

--------------------------------

### TM1Py Setup Dependencies

Source: https://github.com/cubewise-code/tm1py/blob/master/Tests/_gh_README.md

This Python code snippet shows the `install_requires` and `extras_require` sections for `setup.py`. It lists the core dependencies for TM1Py and optional dependencies for features like pandas and development/testing tools.

```python
install_requires=[
    'ijson',
    'requests',
    'pytz',
    'requests_negotiate_sspi;platform_system=="Windows"',
    'mdxpy>=1.3.1'],
extras_require={
    "pandas": ["pandas"],
    "dev": [
        "pytest",
        "pytest-xdist"
    ],
    "unit_test": [
        "pandas",
        "pytest",
        "pytest-xdist",
        "python-dateutil"
    ],
},
```

--------------------------------

### Sample JSON for tm1-12-mscp TM1_CONNECTION

Source: https://github.com/cubewise-code/tm1py/blob/master/Tests/_gh_README.md

Example JSON structure for the TM1_CONNECTION variable for a TM1 12 managed service provider environment.

```json
{
    "base_url": "https://us-east-1.planninganalytics.saas.ibm.com/api/<TenantId>/v0/tm1/<DatabaseName>/",
    "user": "apikey",
    "password": "<TheActualApiKey>",
    "async_requests_mode": true,
    "ssl": true,
    "verify": true,
    "session_context": "gh_unittest"
}
```

--------------------------------

### Sample JSON for tm1-11-onprem TM1_CONNECTION_SECRET

Source: https://github.com/cubewise-code/tm1py/blob/master/Tests/_gh_README.md

Example JSON structure for the TM1_CONNECTION_SECRET for an on-premises TM1 11 environment.

```json
{
  "password": "apple"
}
```

--------------------------------

### Organize Python Imports

Source: https://github.com/cubewise-code/tm1py/blob/master/docs/how-to-contribute.md

Follow this import structure: standard library, third-party libraries, and then local application imports. This example demonstrates the recommended organization.

```python
# Standard library imports
from pathlib import Path
from typing import List

# Third-party imports
import pandas as pd

# Local application imports
from TM1py import TM1Service
```

--------------------------------

### Clone TM1py Repository

Source: https://github.com/cubewise-code/tm1py/blob/master/docs/README.md

Clone the TM1py repository to your local machine to start working with the documentation.

```bash
git clone https://github.com/cubewise-code/tm1py.git
cd tm1py
```

--------------------------------

### Install TM1Py in Development Mode

Source: https://github.com/cubewise-code/tm1py/blob/master/docs/how-to-contribute.md

Install TM1Py using pip in editable mode, including development and pandas dependencies. This allows changes in your local code to be reflected immediately.

```bash
pip install -e .[pandas,dev]
```

--------------------------------

### Sample JSON for tm1-11-cloud TM1_CONNECTION_SECRET

Source: https://github.com/cubewise-code/tm1py/blob/master/Tests/_gh_README.md

Example JSON structure for the TM1_CONNECTION_SECRET for a cloud-hosted TM1 11 environment.

```json
{
  "password": "<NonInteractiveAccountPwd>"
}
```

--------------------------------

### Sample JSON for tm1-12-mscp TM1_CONNECTION_SECRET

Source: https://github.com/cubewise-code/tm1py/blob/master/Tests/_gh_README.md

Example JSON structure for the TM1_CONNECTION_SECRET for a TM1 12 managed service provider environment.

```json
{
  "password": "<TheActualApiKey>"
}
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/cubewise-code/tm1py/blob/master/docs/README.md

Use MkDocs to serve the documentation locally for previewing changes. Access it via http://127.0.0.1:8000/.

```bash
mkdocs serve
```

--------------------------------

### Create and Activate Virtual Environment

Source: https://github.com/cubewise-code/tm1py/blob/master/docs/how-to-contribute.md

Create a Python virtual environment for development and activate it. The command for activation differs between operating systems.

```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

--------------------------------

### Run All TM1py Tests (Linux/macOS)

Source: https://github.com/cubewise-code/tm1py/blob/master/Tests/_readme.md

Execute all TM1py tests from the command line on Linux or macOS. This command initiates the test suite located in the Tests directory.

```bash
pytest ./Tests/
```

--------------------------------

### Run Specific Test File (Linux/macOS)

Source: https://github.com/cubewise-code/tm1py/blob/master/Tests/_readme.md

Execute a specific TM1py test file from the Tests directory on Linux or macOS. Replace 'ChoreService_test.py' with the desired test file.

```bash
pytest ./Tests/ChoreService_test.py
```

--------------------------------

### Configure TM1py Tests

Source: https://github.com/cubewise-code/tm1py/blob/master/Tests/_readme.md

Copy the template configuration file and specify your TM1 instance details. Ensure specific configuration parameters are set for debugging and sandboxing.

```bash
cp Tests/config.ini.template Tests/config.ini
# Specify your instance coordinates in the config.ini file as tm1srv01
# EnableSandboxDimension config parameter must be set to F for the target TM1 instance
# EnableTIDebugging config parameter must be set to T for the target TM1 instance
```

--------------------------------

### Commit and Push Changes

Source: https://github.com/cubewise-code/tm1py/blob/master/docs/README.md

Commit your documentation changes and push them to the repository.

```bash
git add .
git commit -m "Update documentation"
git push
```

--------------------------------

### Connect to TM1 11 On-Premise

Source: https://github.com/cubewise-code/tm1py/blob/master/docs/getting-started.md

Connect to a TM1 11 on-premise instance using TM1Service. Ensure correct address, port, user, and password.

```python
from TM1py.Services import TM1Service

with TM1Service(address='localhost', port=8001, user='admin', password='apple', ssl=True) as tm1:
    print(tm1.server.get_product_version())
```

--------------------------------

### Run All TM1py Tests (Windows)

Source: https://github.com/cubewise-code/tm1py/blob/master/Tests/_readme.md

Execute all TM1py tests from the command line on a Windows system. This command initiates the test suite located in the Tests directory.

```bash
pytest .\Tests\
```

--------------------------------

### Format and Lint Python Code with Black and Ruff

Source: https://github.com/cubewise-code/tm1py/blob/master/docs/how-to-contribute.md

Use these commands to format your Python code using Black and to check for linting issues and organize imports with Ruff. Ruff's `--fix` option can automatically resolve some issues.

```bash
# Format code
black .

# Check imports and linting
ruff check .

# Auto-fix linting issues
ruff check --fix .
```

--------------------------------

### Run Specific Test File (Windows)

Source: https://github.com/cubewise-code/tm1py/blob/master/Tests/_readme.md

Execute a specific TM1py test file from the Tests directory on a Windows system. Replace 'ChoreService_test.py' with the desired test file.

```bash
pytest .\Tests\ChoreService_test.py
```

--------------------------------

### Connect to TM1 12 On-Premise with Access Token

Source: https://github.com/cubewise-code/tm1py/blob/master/docs/getting-started.md

Connect to TM1 12 on-premise using a dictionary of parameters including base_url, user, access token, and async mode.

```python
params = {
    "base_url": "https://pa12.dev.net/api/<InstanceId>/v0/tm1/<DatabaseName>",
    "user": "8643fd6....8a6b",
    "access_token":"<TheActualAccessToken>",
    "async_requests_mode": True,
    "ssl": True,
    "verify": True
}

with TM1Service(**params) as tm1:
    print(tm1.server.get_product_version())
```

--------------------------------

### Connect to TM1 12 On-Premise/Cloud Pak For Data

Source: https://github.com/cubewise-code/tm1py/blob/master/docs/getting-started.md

Connect to TM1 12 on-premise or Cloud Pak For Data using service address, instance, database, and application client credentials.

```python
with TM1Service(
        address="tm1-ibm-operands-services.apps.cluster.your-cluster.company.com",
        instance="your instance name",
        database="your database name",
        application_client_id="client id",
        application_client_secret="client secret",
        user="admin",
        ssl=True) as tm1:

    print(tm1.server.get_product_version())
```

--------------------------------

### Run Tests with Pytest

Source: https://github.com/cubewise-code/tm1py/blob/master/docs/how-to-contribute.md

Execute the test suite using Pytest. This requires access to a TM1 instance and is essential for verifying your changes.

```bash
pytest Tests/
```

--------------------------------

### Connect to TM1 11 on IBM Cloud

Source: https://github.com/cubewise-code/tm1py/blob/master/docs/getting-started.md

Connect to TM1 11 on IBM Cloud using the base_url and non-interactive user credentials. SSL and verification are enabled.

```python
with TM1Service(
        base_url='https://mycompany.planning-analytics.ibmcloud.com/tm1/api/tm1/',
        user="non_interactive_user",
        namespace="LDAP",
        password="U3lSn5QLwoQZY2",
        ssl=True,
        verify=True,
        async_requests_mode=True) as tm1:
    print(tm1.server.get_product_version())
```

--------------------------------

### Format Code with Black and Ruff

Source: https://github.com/cubewise-code/tm1py/blob/master/docs/how-to-contribute.md

Apply code formatting using Black and fix linting issues with Ruff. These commands should be run before committing changes.

```bash
black .
ruff check --fix .
```

--------------------------------

### Clone TM1Py Repository

Source: https://github.com/cubewise-code/tm1py/blob/master/docs/how-to-contribute.md

Clone your forked repository to your local machine. Replace YOUR_USERNAME with your GitHub username.

```bash
git clone https://github.com/YOUR_USERNAME/tm1py.git
```

--------------------------------

### Create a New Feature Branch

Source: https://github.com/cubewise-code/tm1py/blob/master/docs/how-to-contribute.md

Create a new Git branch for your feature or bug fix. Use a descriptive name for your branch.

```bash
git checkout -b your-feature-name
```

--------------------------------

### Run TM1Py Tests with Pytest

Source: https://github.com/cubewise-code/tm1py/blob/master/docs/how-to-contribute.md

Execute the test suite using Pytest. You can run all tests, a specific file, or use the verbose flag for detailed output. Ensure TM1 instances are configured for testing.

```bash
# Run all tests
pytest Tests/

# Run specific test file
pytest Tests/test_cube_service.py

# Run with verbose output
pytest Tests/ -v
```

--------------------------------

### TM1Py Integration Tests GitHub Actions Workflow

Source: https://github.com/cubewise-code/tm1py/blob/master/Tests/_gh_README.md

This YAML file defines a GitHub Actions workflow to run TM1Py integration tests. It uses a matrix strategy to test against multiple environments in parallel and handles environment variables and secrets for TM1 connections.

```yaml
name: TM1Py Integration Tests

on:
  workflow_dispatch:
    inputs:
      environments:
        description: 'JSON array of environments to test (e.g., ["tm1-11-onprem", "tm1-11-cloud"])'
        required: true
        default: '["tm1-11-onprem","tm1-11-cloud","tm1-12-mcsp"]'

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        environment: ${{ fromJson(github.event.inputs.environments) }}
    environment: ${{ matrix.environment }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'

      - name: Install dependencies
        run: |
          pip install -e .[unit_test]

      - name: Retrieve TM1 Connection Details
        id: get-connection
        run: echo "Retrieving TM1 connection details"
        env:
          TM1_CONNECTION: ${{ vars.TM1_CONNECTION }}
          TM1_CONNECTION_SECRET: ${{ secrets.TM1_CONNECTION_SECRET }}

      - name: Generate config.ini
        run: |
          python Tests/resources/generate_config.py
        env:
          TM1_CONNECTION: ${{ vars.TM1_CONNECTION }}
          TM1_CONNECTION_SECRET: ${{ secrets.TM1_CONNECTION_SECRET }}

      - name: Run tests
        run: pytest Tests/

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: test-results-${{ matrix.environment }}
          path: Tests/test-reports/

      # Optional: Post results to PR
      - name: Post comment to PR
        if: always() && github.event_name == 'workflow_dispatch' && github.event.pull_request
        uses: actions/github-script@v6
        with:
          script: |
            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.payload.pull_request.number,
              body: 'Tests completed for environment: ${{ matrix.environment }}. Check artifacts for details.'
            })
```

--------------------------------

### Connect to TM1 12 PAaaS

Source: https://github.com/cubewise-code/tm1py/blob/master/docs/getting-started.md

Connect to TM1 12 PAaaS using a dictionary of parameters including base_url, API key, and async mode.

```python
from TM1py import TM1Service

params = {
    "base_url": "https://us-east-1.planninganalytics.saas.ibm.com/api/<TenantId>/v0/tm1/<DatabaseName>/",
    "user": "apikey",
    "password": "<TheActualApiKey>",
    "async_requests_mode": True,
    "ssl": True,
    "verify": True
}

with TM1Service(**params) as tm1:
    print(tm1.server.get_product_version())
```

--------------------------------

### Release Label Mapping

Source: https://github.com/cubewise-code/tm1py/blob/master/docs/how-to-contribute.md

This table outlines the mapping between release labels, the type of version bump they trigger, and when to use them. It's crucial for maintainers to select the correct label before merging a PR.

```markdown
| Label                        | Version Bump      | When to Use                                                       |
|------------------------------|-------------------|-------------------------------------------------------------------|
| `release:patch`              | `2.1.5` → `2.1.6` | Bug fixes, small improvements                                     |
| `release:minor`              | `2.1.5` → `2.2.0` | New features, enhancements                                        |
| `release:major`              | `2.1.5` → `3.0.0` | Breaking changes, major updates                                   |
| `skip-release` (or no label) | No version bump   | Docs, tests, CI changes, or changes you don't want to release yet |
```

--------------------------------

### Create a Private Subset in TM1

Source: https://github.com/cubewise-code/tm1py/blob/master/README.md

Connects to a TM1 instance and creates a private subset named 'Q1' in the 'Month' dimension with specified elements.

```python
with TM1Service(address='localhost', port=8001, user='admin', password='apple', ssl=True) as tm1:
    subset = Subset(dimension_name='Month', subset_name='Q1', elements=['Jan', 'Feb', 'Mar'])
    tm1.subsets.create(subset, private=True)
```

--------------------------------

### Generate TM1 config.ini Python Script

Source: https://github.com/cubewise-code/tm1py/blob/master/Tests/_gh_README.md

This Python script dynamically generates the `Tests/config.ini` file by reading TM1 connection details and secrets from environment variables. It's used within the GitHub Actions workflow to configure TM1Py connections for tests.

```python
import json
import os

tm1_connection = os.environ.get('TM1_CONNECTION')
tm1_connection_secret = os.environ.get('TM1_CONNECTION_SECRET')

config_content = '[tm1srv01]\n'

if tm1_connection:
    conn_data = json.loads(tm1_connection)
    for key, value in conn_data.items():
        config_content += f"{key}={value}\n"

if tm1_connection_secret:
    secret_data = json.loads(tm1_connection_secret)
    for key, value in secret_data.items():
        config_content += f"{key}={value}\n"

with open('Tests/config.ini', 'w') as f:
    f.write(config_content)
```

--------------------------------

### Add Upstream Remote

Source: https://github.com/cubewise-code/tm1py/blob/master/docs/how-to-contribute.md

Add the upstream remote to your local repository to fetch changes from the main TM1Py project. This is crucial for keeping your fork updated.

```bash
git remote add upstream https://github.com/cubewise-code/tm1py.git
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.