{
  "category": "External data functions",
  "display_name": "PY",
  "entry_kind": "built_in_function",
  "eval_api": {
    "method": "POST",
    "url": "https://handbook.dnacalc.com/api/eval"
  },
  "function_id": "FUNC.PY",
  "implementation_state": {
    "answer_bank": null,
    "detail": "Deferred by policy: the code runs in Microsoft's cloud runtime. DNA Calc does not run this function yet.",
    "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87",
    "in_catalogue": false,
    "state": "deferred",
    "state_label": "Deferred: needs an outside service",
    "summary": "Deferred: needs an outside service",
    "workbook_corpus": null
  },
  "implementations": [],
  "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.PY.json",
  "name": "PY",
  "notes": [],
  "schema": "efh.function-reference/v1",
  "section_order": [
    "what-it-does",
    "try-it",
    "quirks",
    "how-to-implement",
    "version-differences",
    "alternatives"
  ],
  "sections": {
    "alternatives": "\n- Add-ins that run Python on your own machine, for local control of libraries and data.\n- Power Query or worksheet functions, when the calculation does not need Python.\n\n\n",
    "how-to-implement": "\nDNA Calc does not run this function yet. It is deferred by policy, because the answer depends on a back end\nMicrosoft hosts and controls. An implementation needs:\n\n1. **A Python runtime.** A sandboxed interpreter with no access to the host, one per workbook, which keeps its\n   state between cells. Cells run in a defined order, so that order has to be reproduced too.\n2. **The `xl()` bridge.** It must turn references, tables and connections into the runtime's objects, and convert\n   results back. `return_type` 1 needs a cell value that holds a foreign object.\n3. **The library set.** Results depend on the versions of the packages the runtime provides.\n4. **Asynchronous calculation.** A cell can be busy, so recalculation needs states like `#BUSY!` and a timeout.\n5. **Grammar rules.** Refuse non-static arguments and any nesting at entry, as Excel does.\n\nA local runtime would be a different function from Microsoft's: it would need its own name, or a clear statement\nthat answers can differ.\n\n\n",
    "quirks": "\n- **It cannot be nested.** Excel rejects a formula that combines `PY` with other functions. Other cells may\n  read its result, but the call stands alone in its cell.\n- **The formula is hidden.** It does not appear in the formula bar. `FORMULATEXT` still shows it.\n- **Both arguments are frozen.** `PY(A1,0)` and `PY(\"1+1\",B1)` are not accepted, so the code cannot depend on a\n  cell except through `xl()`.\n- **A result can be an object.** With `return_type` 1 the cell holds a Python object, not a worksheet value.\n\n### When the service is unavailable\n\nMicrosoft states that the calculation needs internet access, because it happens in its cloud and not in the\nlocal application. Its troubleshooting article gives these outcomes, in place of a value:\n\n| Error | Meaning given by Microsoft | Suggested action |\n|---|---|---|\n| `#BUSY!` | Still calculating in the cloud | Reset the runtime if it lasts past 60 seconds |\n| `#CONNECT!` | The connection to the cloud needs refreshing | Reset the runtime |\n| `#TIMEOUT!` | The formula passed the maximum execution time | Rerun, reset, or raise the Python Formula Timeout option |\n| `#BLOCKED!` | Connected services are not available to this account | Check access; device-based subscriptions and shared computer activation are not supported |\n\nReset is on Formulas > Python, or Ctrl+Alt+Shift+F9. Microsoft's data security article says the container stays\nonline while the workbook is open or until a timeout. What a saved result shows when a workbook opens offline\nis not stated in these sources and has not been measured.\n\n\n",
    "sources": "\n- [PY function](https://support.microsoft.com/en-us/excel/functions/py-function)\n- [Troubleshoot Python in Excel errors](https://support.microsoft.com/en-us/office/troubleshoot-python-in-excel-errors-7736520d-47ef-43a8-b640-d826afb63249)\n- [Data security and Python in Excel](https://support.microsoft.com/en-us/office/data-security-and-python-in-excel-33cc88a4-4a87-485e-9ff9-f35958278327)\n\n",
    "version-differences": "\nNo Excel answers for this function are recorded here, so no comparison between Excel builds exists. Microsoft's page lists Excel for Microsoft 365 on Windows and Mac. Its troubleshooting\narticle says iPad, iPhone and Android are not supported.\n\n\n",
    "what-it-does": "\n`PY` runs Python code and puts the result in a cell. The code does not run on your computer: it runs in a\ncontainer in Microsoft's cloud, and Excel shows what comes back.\n\n`PY(python_code, return_type)` has two arguments, both required and both fixed at entry.\n\n- **`python_code`** is the program, as static text. It cannot be a cell reference or a calculated value.\n- **`return_type`** is the number 0 or 1. 0 returns an Excel value; 1 returns a Python object held in the cell.\n\nWorksheet data reaches the code through a helper, `xl()`, which reads ranges, names, tables and Power Query\nconnections, with an optional `headers` setting for the first row:\n\n```\n=PY(\"xl(\"\"Table1[#All]\"\", headers=True)\",1)\n```\n\nYou rarely type this formula. Entering `=PY` and choosing it from AutoComplete opens a Python editor, which\nwrites the formula into the cell.\n\n\n"
  },
  "signature": {
    "display": "PY(python_code, return_type)",
    "parameters": [
      {
        "description": null,
        "name": "python_code",
        "optional": false,
        "repeats": false
      },
      {
        "description": null,
        "name": "return_type",
        "optional": false,
        "repeats": false
      }
    ],
    "trailing_repeats": false
  },
  "sources": {
    "metadata": {
      "admission": {
        "label": "deferred",
        "reason": "Deferred by policy: the code runs in Microsoft's cloud runtime. DNA Calc does not run this function yet."
      },
      "arity": {
        "max": 2,
        "min": 2
      },
      "category": "External data functions",
      "classification": {},
      "descriptions": {
        "long": null,
        "short": "Runs Python in Microsoft's cloud runtime",
        "short_source": "dna-calc-own"
      },
      "docs": {
        "english_description": null,
        "microsoft_url": "https://support.microsoft.com/en-us/excel/functions/py-function"
      },
      "entry_kind": "built_in_function",
      "localized_family_names": null,
      "localized_names": [],
      "signature": {
        "display": "PY(python_code, return_type)",
        "parameters": [
          {
            "description": null,
            "name": "python_code",
            "optional": false,
            "repeats": false
          },
          {
            "description": null,
            "name": "return_type",
            "optional": false,
            "repeats": false
          }
        ],
        "trailing_repeats": false
      },
      "surface_name": "PY",
      "version_marker": null,
      "xlcall": null
    },
    "microsoft": "https://support.microsoft.com/en-us/excel/functions/py-function"
  },
  "try_it": {
    "formula": "=PY(\"1+1\",0)",
    "note": "The OneCalc preview has no answer for this function: see the state above.",
    "preview_status": "worksheet-error"
  },
  "url": "https://handbook.dnacalc.com/functions/PY.html",
  "variants": [],
  "versions": []
}