plotly-cloud 0.1.0__py3-none-any.whl

plotly_cloud/exceptions.py

@@ -0,0 +1,198 @@
+"""Custom exceptions for Plotly Cloud CLI."""
+
+from typing import Optional
+
+
+class PlotlyCloudError(Exception):
+    """Base exception for all Plotly Cloud CLI errors."""
+
+    def __init__(self, message: str, details: Optional[str] = None):
+        """Initialize exception with message and optional details."""
+        super().__init__(message)
+        self.message = message
+        self.details = details
+
+    def __str__(self) -> str:
+        """Return formatted error message."""
+        if self.details:
+            return f"{self.message}: {self.details}"
+        return self.message
+
+
+class AuthenticationError(PlotlyCloudError):
+    """Raised when authentication fails."""
+
+    pass
+
+
+class ConfigurationError(PlotlyCloudError):
+    """Raised when configuration is invalid or missing."""
+
+    pass
+
+
+class DeploymentError(PlotlyCloudError):
+    """Raised when deployment operations fail."""
+
+    pass
+
+
+class ApplicationError(PlotlyCloudError):
+    """Raised when application operations fail."""
+
+    pass
+
+
+# Authentication-specific exceptions
+class OAuthClientError(AuthenticationError):
+    """Raised when OAuth client operations fail."""
+
+    pass
+
+
+class TokenError(AuthenticationError):
+    """Raised when token operations fail."""
+
+    pass
+
+
+class CredentialError(AuthenticationError):
+    """Raised when credential operations fail."""
+
+    pass
+
+
+class ForbiddenError(AuthenticationError):
+    """Raised when access is forbidden (HTTP 403)."""
+
+    pass
+
+
+# Configuration-specific exceptions
+class CloudConfigError(ConfigurationError):
+    """Raised when cloud configuration operations fail."""
+
+    pass
+
+
+class EnvironmentError(ConfigurationError):
+    """Raised when environment configuration is invalid."""
+
+    pass
+
+
+# Deployment-specific exceptions
+class DependencyValidationError(DeploymentError):
+    """Raised when dependency validation fails."""
+
+    pass
+
+
+class PackagingError(DeploymentError):
+    """Raised when packaging operations fail."""
+
+    pass
+
+
+class UploadError(DeploymentError):
+    """Raised when upload operations fail."""
+
+    pass
+
+
+class AppCreationError(DeploymentError):
+    """Raised when app creation fails."""
+
+    pass
+
+
+class AppPublishError(DeploymentError):
+    """Raised when app publishing fails."""
+
+    pass
+
+
+class DeploymentClientError(DeploymentError):
+    """Raised when deployment client operations fail."""
+
+    pass
+
+
+# Application-specific exceptions
+class ModuleImportError(ApplicationError):
+    """Raised when module import fails."""
+
+    pass
+
+
+class DashAppError(ApplicationError):
+    """Raised when Dash app operations fail."""
+
+    pass
+
+
+class ServerError(ApplicationError):
+    """Raised when server operations fail."""
+
+    pass
+
+
+# Network-specific exceptions
+class APIError(PlotlyCloudError):
+    """Raised when API operations fail."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        details: Optional[str] = None,
+    ):
+        """Initialize API error with optional status code."""
+        super().__init__(message, details)
+        self.status_code = status_code
+
+    def __str__(self) -> str:
+        """Return formatted error message with status code."""
+        msg = self.message
+        if self.status_code:
+            msg = f"{msg} (HTTP {self.status_code})"
+        if self.details:
+            msg = f"{msg}: {self.details}"
+        return msg
+
+
+class NetworkError(PlotlyCloudError):
+    """Raised when network operations fail."""
+
+    pass
+
+
+class TimeoutError(PlotlyCloudError):
+    """Raised when operations timeout."""
+
+    pass
+
+
+# File system exceptions
+class FileSystemError(PlotlyCloudError):
+    """Raised when file system operations fail."""
+
+    pass
+
+
+class FileNotFoundError(FileSystemError):
+    """Raised when required files are not found."""
+
+    pass
+
+
+class FilePermissionError(FileSystemError):
+    """Raised when file permission operations fail."""
+
+    pass
+
+
+class FileSizeError(FileSystemError):
+    """Raised when file size limits are exceeded."""
+
+    pass

plotly_cloud-0.1.0.dist-info/METADATA

@@ -0,0 +1,294 @@
+Metadata-Version: 2.4
+Name: plotly-cloud
+Version: 0.1.0
+Summary: CLI for interacting with Plotly Cloud to deploy Dash apps
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: dash>=2.0.0
+Requires-Dist: httpx<1.0.0,>=0.24.0
+Requires-Dist: nest-asyncio>=1.6.0
+Requires-Dist: rich>=10.0.0
+Requires-Dist: tomli-w>=1.2.0
+Requires-Dist: tomli>=2.2.1
+Description-Content-Type: text/markdown
+
+# Plotly Cloud CLI
+
+A command-line interface for interacting with Plotly Cloud to publish and manage Dash applications.
+
+## Features
+
+- 🔐 **Authentication**: Login/logout with Plotly Cloud using OAuth
+- 🚀 **Local Development**: Run Dash applications locally with comprehensive dev tools
+- 📦 **Publish**: Publish Dash applications to Plotly Cloud with metadata management
+- ⚙️ **Environment Configuration**: Centralized cloud configuration with staging/production support
+
+## Installation
+
+```bash
+pip install plotly-cloud
+```
+
+## Quick Start
+
+### 1. Login to Plotly Cloud
+
+```bash
+plotly login
+```
+
+This will open your browser for OAuth authentication.
+
+### 2. Run a Dash Application
+
+```bash
+plotly run app:app
+```
+
+This runs your Dash app from the `app` module, using the `app` variable.
+
+### 3. Publish to Plotly Cloud
+
+```bash
+# For new applications (first publish)
+plotly publish --name "My App" --description "My application description"
+
+# For existing applications (with default polling)
+plotly publish
+
+# Publish without polling status
+plotly publish --poll-status=false
+```
+
+### 4. Logout
+
+```bash
+plotly logout
+```
+
+## Environment Configuration
+
+The CLI uses a `cloud-env.toml` file for environment-specific configuration (OAuth client IDs, API URLs). This file is gitignored and should be created during development or at packaging time.
+
+## Usage
+
+### Authentication Commands
+
+#### Login
+```bash
+plotly login [--browser | --no-browser]
+```
+
+Options:
+- `--browser`: Open browser for authentication (default)
+- `--no-browser`: Don't open browser automatically
+
+#### Logout
+```bash
+plotly logout
+```
+
+#### Check Current User
+```bash
+plotly whoami
+```
+
+Show current user information if logged in with a valid token. If the token is invalid, it will automatically clear the credentials.
+
+### Running Applications
+
+#### Basic Usage
+```bash
+plotly run <module:variable>
+```
+
+Examples:
+```bash
+plotly run app:app          # Run app from app.py
+plotly run myapp:dashboard  # Run dashboard from myapp.py
+plotly run main             # Run from main.py (looks for first Dash app)
+```
+
+#### Advanced Options
+
+```bash
+plotly run app:app --host 0.0.0.0 --port 8080 --debug
+```
+
+**Server Options:**
+- `--host`: Host IP address (default: 127.0.0.1)
+- `--port, -p`: Port number (default: 8050)
+- `--proxy`: Proxy configuration
+- `--debug, -d`: Enable debug mode
+
+**Development Tools:**
+- `--dev-tools-ui`: Enable dev tools UI
+- `--dev-tools-props-check`: Enable component prop validation
+- `--dev-tools-serve-dev-bundles`: Enable serving dev bundles
+- `--dev-tools-hot-reload`: Enable hot reloading
+- `--dev-tools-hot-reload-interval`: Hot reload polling interval (default: 3.0s)
+- `--dev-tools-hot-reload-watch-interval`: File watch interval (default: 0.5s)
+- `--dev-tools-hot-reload-max-retry`: Max failed reload attempts (default: 8)
+- `--dev-tools-silence-routes-logging`: Silence Werkzeug route logging
+- `--dev-tools-disable-version-check`: Disable Dash version upgrade check
+- `--dev-tools-prune-errors`: Prune tracebacks to user code only
+
+### Publishing Commands
+
+#### Publish Application
+```bash
+plotly publish [OPTIONS]
+```
+
+Publish your Dash application to Plotly Cloud with automatic status polling.
+
+**Options:**
+- `--project-path`: Path to project directory (default: current directory)
+- `--config`: Path to configuration file (default: plotly-cloud.toml)
+- `--name`: Application name (required for first publish)
+- `--description`: Application description (optional)
+- `--output`: Output path for publish zip file (default: temporary file)
+- `--keep-zip`: Keep the publish zip file after upload
+- `--poll-status`: Poll publish status until completion (default: true)
+- `--poll-interval`: Polling interval in seconds (default: 1.0)
+- `--poll-timeout`: Polling timeout in seconds (default: 180 = 3 minutes)
+
+**Examples:**
+```bash
+# Publish with default settings (includes status polling)
+plotly publish
+
+# Publish new app with custom name and description
+plotly publish --name "My Dashboard" --description "Sales analytics dashboard"
+
+# Publish without status polling
+plotly publish --poll-status=false
+
+# Publish with custom polling settings
+plotly publish --poll-interval=2.0 --poll-timeout=300
+
+# Publish and keep the zip file
+plotly publish --output=my-app.zip --keep-zip
+```
+
+#### Check Application Status
+```bash
+plotly status [OPTIONS]
+```
+
+Get current status and details of your published application.
+
+**Options:**
+- `--project-path`: Path to project directory (default: current directory)
+- `--config`: Path to configuration file (default: plotly-cloud.toml)
+
+**Example:**
+```bash
+plotly status
+```
+
+## Requirements
+
+- Python 3.9+
+
+### Python Dependencies
+
+- `httpx>=0.24.0` - HTTP client for API requests
+- `dash>=2.0.0` - Dash framework
+- `rich>=10.0.0` - Rich terminal formatting
+
+### Development Dependencies
+
+- `pytest>=6.0` - Testing framework
+- `ruff>=0.1.0` - Code linting and formatting
+- `pyright>=1.1.0` - Type checking
+
+## Development
+
+### Setup
+
+We use [`uv`](https://docs.astral.sh/uv/) to manage dependencies and [Just](https://github.com/casey/just) is used for task automation. Install them and use our Justfile for common development tasks:
+
+1. Clone the repository
+2. Install uv: `curl -LsSf https://astral.sh/uv/install.sh | sh` or on windows: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`
+3. Install Just: `cargo install just` or see [installation docs](https://github.com/casey/just#installation)
+4. Setup the development environment:
+   ```bash
+   # Install dependencies
+   just install
+   
+   # Setup cloud environment configuration
+   just setup-cloud-env "your-staging-client-id" "your-production-client-id"
+   
+   # Install CLI in development mode
+   just install-cli
+   ```
+
+### Development Commands
+
+Run `just` or `just --list` to see all available commands:
+
+```bash
+# Testing
+just test                    # Run all tests
+just test-cov               # Run tests with coverage
+just test-file tests/test_commands.py  # Run specific test file
+
+# Code Quality
+just lint                   # Run linting
+just lint-fix              # Run linting with auto-fix
+just format                 # Format code
+just quality                # Run all quality checks (lint + typecheck + test)
+
+# Cloud Configuration
+just setup-cloud-env <staging_id> [production_id]  # Setup cloud config
+just show-cloud-config      # Display current configuration
+
+# Publishing
+just publish [path]          # Publish to cloud (default: current directory)
+
+# Development
+just install-cli            # Install CLI in development mode
+just test-cli              # Test CLI after installation
+just run-example app:app    # Run example Dash app
+
+# Maintenance
+just clean                  # Clean build artifacts
+just build                  # Build package
+```
+
+### Alternative Setup (without Just)
+
+If you prefer not to use Just:
+
+1. Create a virtual environment:
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+   ```
+2. Install in development mode:
+   ```bash
+   pip install -e ".[dev]"
+   ```
+
+### Project Structure
+
+```
+plotly-cloud-cli/
+├── plotly_cloud/
+│   ├── __init__.py          # Package initialization
+│   ├── cli.py               # Main CLI entry point
+│   └── _commands.py         # Command implementations
+├── pyproject.toml           # Project configuration
+├── uv.lock                  # Dependency lock file
+├── .gitignore              # Git ignore rules
+└── README.md               # This file
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+For issues and questions, please open an issue on the GitHub repository.

plotly_cloud-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+plotly_cloud/__init__.py,sha256=wpj79Ze3y-ZOaVREZBKU1wGt87HKfGyXM6-iHipgc7c,55
+plotly_cloud/_api_types.py,sha256=_sKJb6Bk7e-2ucLRGmdr8Nq9-8G-BLU2EtVLA25HkKM,1103
+plotly_cloud/_changes.py,sha256=YQJGChUzSGCgQOVnsA98vqWLARaY893UqVePYsCAhh8,2084
+plotly_cloud/_cloud_env.py,sha256=8hlYB2x6V7KsNmy80MKRNDmxuQiPna71_nhK7haF23E,2941
+plotly_cloud/_commands.py,sha256=FbJGOBs1VJ171eTqoOgfBIAlq_x1VoaMhf0HBElLKkM,35015
+plotly_cloud/_definitions.py,sha256=UmzzhV6evNNWYW_eAvnbdplaoSKWuTQtWuJ1AkjFgis,2388
+plotly_cloud/_deploy.py,sha256=Fpsu7L9mTyh3wEODfMMlAWmFBzfsoYgjg_IK6xG97RE,16198
+plotly_cloud/_devtool_hooks.py,sha256=j16E5x5UiWwkgTjSBEFtQ71NOTaAYkofM9CIAfNMnbE,1504
+plotly_cloud/_devtool_publish_rpc.py,sha256=-cCUB0KIiM2n5pb2_K5o4H6W9YaRSh4KAJEpYcpzIdk,10641
+plotly_cloud/_oauth.py,sha256=yCi6tn17bLmhZiajUcliWjxZ9mEt0iMXIS9dGojPsH0,12377
+plotly_cloud/_parser.py,sha256=EoyehZZRy_A8PHO2yTMUkJcXTgztgh-7gAQF2uaP640,5795
+plotly_cloud/cli.py,sha256=keez1KpXxZEDLWYo58VnvzPBG6mctMf1aNqDWGqfvq4,10474
+plotly_cloud/cloud-env.toml,sha256=Em7c0Q3vaCqXmWdEH-Re32eo4Na_HVQ7mJyMFY80KZ8,248
+plotly_cloud/cloud_devtools.css,sha256=3y2Q9NzM1arrkniLGZHfkiqtttuD5X7LkmCuxrkMRtI,3730
+plotly_cloud/cloud_devtools.js,sha256=BQWc-dzs1EFmruXJJvZMphtj7JvR5RMKLjz0KTsvxJk,41840
+plotly_cloud/exceptions.py,sha256=k5uvHh41oKWsRiVBSVFCMbtHygbkgTkq_uJJ1Q3wlG4,4033
+plotly_cloud-0.1.0.dist-info/METADATA,sha256=wHowUtRnJchfzwTu8ZqRKWGzRGA-JWG2_4xMqZ2srYg,8173
+plotly_cloud-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+plotly_cloud-0.1.0.dist-info/entry_points.txt,sha256=iZVffCSWjpG8Ht2HZAJDwZBmG-kVlIbH_V6SF8cwLNY,115
+plotly_cloud-0.1.0.dist-info/licenses/LICENSE,sha256=ElWBU-rl1xjn3Pvcguv5MNomrIMao1mPtuT_j8Q6WaI,1068
+plotly_cloud-0.1.0.dist-info/RECORD,,

plotly_cloud-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

plotly_cloud-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+plotly = plotly_cloud.cli:main
+
+[dash_hooks]
+plotly_cloud_devtools = plotly_cloud._devtool_hooks

plotly_cloud-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Plotly, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.