{"id":7486,"library":"p4python","title":"P4Python: Perforce Helix Core API","description":"P4Python is the official Python API for Perforce Helix Core, allowing Python applications to interact with Perforce servers. It enables scripting of Perforce operations like file management, changelists, jobs, and user administration. The library is actively maintained with frequent releases, currently at version 2025.2.2863679.","status":"active","version":"2025.2.2863679","language":"en","source_language":"en","source_url":"https://github.com/perforce/p4python","tags":["perforce","vcs","scm","devops","version-control","api-client"],"install":[{"cmd":"pip install p4python","lang":"bash","label":"Install P4Python"}],"dependencies":[],"imports":[{"symbol":"P4","correct":"from P4 import P4"},{"symbol":"P4Exception","correct":"from P4 import P4Exception"}],"quickstart":{"code":"import os\nfrom P4 import P4, P4Exception\n\n# Configure connection details (prefer environment variables or explicit settings)\n# Example: P4PORT='ssl:perforce:1666', P4USER='your_user', P4CLIENT='your_workspace'\np4_port = os.environ.get('P4PORT', 'perforce:1666') # Replace with your server:port\np4_user = os.environ.get('P4USER', 'guest')       # Replace with your Perforce username\np4_client = os.environ.get('P4CLIENT', 'cli_workspace') # Replace with your client workspace name\np4_password = os.environ.get('P4PASSWD', '')    # Only needed if using password authentication\n\ntry:\n    # Initialize P4 object\n    p4 = P4()\n\n    # Set connection parameters\n    p4.port = p4_port\n    p4.user = p4_user\n    p4.client = p4_client\n    if p4_password:\n        p4.password = p4_password\n\n    # Connect to the Perforce server\n    p4.connect()\n\n    # Log in if required (if 'p4 login' is enforced)\n    # p4.login()\n\n    # Run a simple Perforce command\n    info_output = p4.run('info')\n    print(f\"Successfully connected to Perforce server: {info_output[0]['serverAddress']}\")\n    print(f\"Current Perforce user: {info_output[0]['userName']}\")\n\n    # Get a list of clients\n    clients = p4.run('clients')\n    print(f\"Found {len(clients)} clients.\")\n\nexcept P4Exception as e:\n    # P4Exception catches errors reported by the Perforce server or API\n    for error_msg in e.errors:\n        print(f\"P4API Error: {error_msg}\")\nexcept Exception as e:\n    # Catch other unexpected Python errors\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    # Always ensure disconnection\n    if 'p4' in locals() and p4.connected():\n        p4.disconnect()\n        print(\"Disconnected from Perforce server.\")","lang":"python","description":"This quickstart demonstrates how to establish a connection to a Perforce Helix Core server, run a basic 'info' command, and properly disconnect. It prioritizes using environment variables for credentials where possible, falling back to placeholders."},"warnings":[{"fix":"Always call `p4.disconnect()` in a `finally` block to ensure the connection is closed, even if errors occur. The `P4` object is not a context manager.","message":"Failing to disconnect from the Perforce server can leave open connections, consuming server resources and potentially causing issues for long-running scripts.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Explicitly set `p4.charset = 'utf8'` (or the appropriate charset for your server) immediately after creating the `P4` object and before connecting. Ensure your Python script itself is saved with UTF-8 encoding.","message":"P4Python's handling of Unicode and character encodings can be tricky, especially with older servers or mixed environments, potentially leading to `UnicodeDecodeError` or corrupted text.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Explicitly set `p4.port`, `p4.user`, `p4.client`, and `p4.password` attributes directly on the `P4` object in your code. Use `os.environ.get()` to retrieve default values if you still want environment variable fallback.","message":"Relying solely on `P4PORT`, `P4USER`, `P4CLIENT`, `P4PASSWD` environment variables can lead to brittle scripts, especially when running multiple commands or managing different server/user contexts.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Before `p4.connect()`, ensure you set `p4.port = 'your_server:your_port'` (e.g., `p4.port = 'perforce:1666'`) or set the `P4PORT` environment variable.","cause":"The `P4PORT` environment variable is not set, and `p4.port` was not explicitly configured in the script.","error":"P4Exception: connect: P4PORT not set."},{"fix":"Ensure `p4.connect()` is called and succeeds before attempting to run any Perforce commands like `p4.run('info')`.","cause":"A Perforce command was attempted before `p4.connect()` was successfully called.","error":"P4Exception: Not connected!"},{"fix":"Verify that `p4.client` is set to an existing, valid client workspace name. You may need to create a new client workspace using `p4 client` on the command line or `p4.run('client', '-i', client_spec)` in your script.","cause":"The client workspace specified by `p4.client` or the `P4CLIENT` environment variable does not exist on the server or is not accessible to the current user.","error":"P4Exception: client 'your_client' unknown - use 'p4 client' to create it."},{"fix":"Set `p4.charset = 'utf8'` (or the appropriate charset like 'shiftjis', 'iso8859-1') after initializing `P4()` and before `p4.connect()`. Ensure your script's source file is also saved with the correct encoding (e.g., UTF-8).","cause":"Perforce server output contains characters that Python's default decoder cannot handle, often due to mismatched `charset` settings between client and server.","error":"UnicodeDecodeError: 'utf-8' codec can't decode byte ..."}]}