From 17658865dacec525043c42ec2467f410e567614c Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Wed, 19 Apr 2023 15:51:20 +0200 Subject: [PATCH 1/8] Kernelspec JSON schema --- kernelspec-spec/kernelspec-spec.md | 29 +++++++++++++++++ kernelspec-spec/kernelspec.schema.json | 44 ++++++++++++++++++++++++++ 2 files changed, 73 insertions(+) create mode 100644 kernelspec-spec/kernelspec-spec.md create mode 100644 kernelspec-spec/kernelspec.schema.json diff --git a/kernelspec-spec/kernelspec-spec.md b/kernelspec-spec/kernelspec-spec.md new file mode 100644 index 00000000..88fa8ae8 --- /dev/null +++ b/kernelspec-spec/kernelspec-spec.md @@ -0,0 +1,29 @@ +--- +title: kernelspec specification +authors: Johan Mabille +issue-number: XX +pr-number: XX +date-started: "2023-04-19" +--- + +# Specification of the kernelspec + +## Problem + +The kernelspec configuration file is documented aside the kernel protocol documentation, but it is not +*specified*. Besides, it might be unclear whether the kernelspec is part of the kernel protocol, or +independent. + +## Proposed Enhancement + +We propose to specify the kernelspec with the JSON schema joined in this PR. The specification is conform +to [the current description of the kernelspec](https://jupyter-client.readthedocs.io/en/stable/kernels.html#kernel-specs), +and adds an optional `protocol_version` field. + +[A dedicated repo](https://github.com/jupyter-standards/kernelspec) for the specification and the documentation of +the kernelspec has been created. + +### Impact on existing implementations + +None, this JEP only adds an optional field in the kernelspec. + diff --git a/kernelspec-spec/kernelspec.schema.json b/kernelspec-spec/kernelspec.schema.json new file mode 100644 index 00000000..a0d3f635 --- /dev/null +++ b/kernelspec-spec/kernelspec.schema.json @@ -0,0 +1,44 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://standards.jupyter.org/kernelspec.schema.json", + "title": "Kernelspec", + "description": "Specification of the kernelspec file", + "type": "object", + "properties": { + "argv": { + "description": "A list of command line arguments used to start the kernel. The text {connection_file} in any argument will be replaced with the path to the connection file.", + "type": "array", + "items": { + "type": "string" + }, + "minItems": 3 + }, + "display_name": { + "description": "The kernel’s name as it should be displayed in the UI. Unlike the kernel name used in the API, this can contain arbitrary unicode characters.", + "type": "string" + }, + "language": { + "description": "The name of the language of the kernel. When loading notebooks, if no matching kernelspec key (may differ across machines) is found, a kernel with a matching language will be used. This allows a notebook written on any Python or Julia kernel to be properly associated with the user’s Python or Julia kernel, even if they aren’t listed under the same name as the author’s.", + "type": "string" + }, + "kernel_protocol_version": { + "description": "The version of protocol this kernel implements. If not specified, the client will assume the version is <5.5 until it can get it via the kernel_info request.", + "type": "string" + }, + "interrupt_mode": { + "description": "May be either signal or message and specifies how a client is supposed to interrupt cell execution on this kernel, either by sending an interrupt signal via the operating system’s signalling facilities (e.g. SIGINT on POSIX systems), or by sending an interrupt_request message on the control channel (see Kernel interrupt). If this is not specified the client will default to signal mode.", + "type": "string", + "enume": ["signal", "message"] + }, + "env": { + "description": "A dictionary of environment variables to set for the kernel. These will be added to the current environment variables before the kernel is started. Existing environment variables can be referenced using ${} and will be substituted with the corresponding value. Administrators should note that use of ${} can expose sensitive variables and should use only in controlled circumstances.", + "type": "object", + "additionalProperties": {"type": "string" } + }, + "metadata": { + "description": "A dictionary of additional attributes about this kernel; used by clients to aid in kernel selection. Metadata added here should be namespaced for the tool reading and writing that metadata.", + "type": "object" + } + }, + "required": ["argv", "display_name", "language"] +} From 707e492ee09516972f934e1261c08eb92c18f27f Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Wed, 19 Apr 2023 18:14:34 +0200 Subject: [PATCH 2/8] Changes according to review --- kernelspec-spec/kernelspec-spec.md | 13 +++++-------- kernelspec-spec/kernelspec.schema.json | 17 ++++++++++------- 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/kernelspec-spec/kernelspec-spec.md b/kernelspec-spec/kernelspec-spec.md index 88fa8ae8..efcf35d6 100644 --- a/kernelspec-spec/kernelspec-spec.md +++ b/kernelspec-spec/kernelspec-spec.md @@ -10,18 +10,15 @@ date-started: "2023-04-19" ## Problem -The kernelspec configuration file is documented aside the kernel protocol documentation, but it is not -*specified*. Besides, it might be unclear whether the kernelspec is part of the kernel protocol, or -independent. +The kernelspec configuration file is [documented](https://github.com/jupyter/jupyter_client/blob/main/docs/kernels.rst) aside the kernel protocol documentation, and an [implementation](https://github.com/jupyter/jupyter_client/blob/main/jupyter_client/kernelspec.py#L21) is available, but it is not *specified*. Besides, it might be unclear whether the kernelspec is part of the kernel protocol, or independent. ## Proposed Enhancement -We propose to specify the kernelspec with the JSON schema joined in this PR. The specification is conform -to [the current description of the kernelspec](https://jupyter-client.readthedocs.io/en/stable/kernels.html#kernel-specs), -and adds an optional `protocol_version` field. +We propose to specify the kernelspec with the JSON schema joined in this PR. The specification would reflect +[the current description of the kernelspec](https://jupyter-client.readthedocs.io/en/stable/kernels.html#kernel-specs), +and adds an optional `kernel_protocol_version` field. -[A dedicated repo](https://github.com/jupyter-standards/kernelspec) for the specification and the documentation of -the kernelspec has been created. +The specification and the documentation of the kernelspec will be stored aside [those of the kernel protocol](https://github.com/jupyter-standards/kernel-protocol) ### Impact on existing implementations diff --git a/kernelspec-spec/kernelspec.schema.json b/kernelspec-spec/kernelspec.schema.json index a0d3f635..d959ee5d 100644 --- a/kernelspec-spec/kernelspec.schema.json +++ b/kernelspec-spec/kernelspec.schema.json @@ -1,9 +1,10 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://standards.jupyter.org/kernelspec.schema.json", - "title": "Kernelspec", - "description": "Specification of the kernelspec file", + "$id": "https://schemas.jupyter.org/kernelspec-v1.0.schema.json", + "title": "Jupyter Kernelspec", + "description": "A description of the data required to start and manage a Jupyter Kernel", "type": "object", + "properties": { "argv": { "description": "A list of command line arguments used to start the kernel. The text {connection_file} in any argument will be replaced with the path to the connection file.", @@ -22,13 +23,14 @@ "type": "string" }, "kernel_protocol_version": { - "description": "The version of protocol this kernel implements. If not specified, the client will assume the version is <5.5 until it can get it via the kernel_info request.", - "type": "string" + "description": "The version of protocol this kernel implements. If not specified, the client will assume the version is <5.5 until it can get it via the kernel_info request. The kernel protocol uses semantic versioning (SemVer).", + "type": "string", + "pattern": "^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$" }, "interrupt_mode": { "description": "May be either signal or message and specifies how a client is supposed to interrupt cell execution on this kernel, either by sending an interrupt signal via the operating system’s signalling facilities (e.g. SIGINT on POSIX systems), or by sending an interrupt_request message on the control channel (see Kernel interrupt). If this is not specified the client will default to signal mode.", "type": "string", - "enume": ["signal", "message"] + "enum": ["signal", "message"] }, "env": { "description": "A dictionary of environment variables to set for the kernel. These will be added to the current environment variables before the kernel is started. Existing environment variables can be referenced using ${} and will be substituted with the corresponding value. Administrators should note that use of ${} can expose sensitive variables and should use only in controlled circumstances.", @@ -37,7 +39,8 @@ }, "metadata": { "description": "A dictionary of additional attributes about this kernel; used by clients to aid in kernel selection. Metadata added here should be namespaced for the tool reading and writing that metadata.", - "type": "object" + "type": "object", + "additionalProperties": {"type": "object"} } }, "required": ["argv", "display_name", "language"] From 5c97fdefc16ce296345bd1321f1acf3b02af34e7 Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Sat, 22 Apr 2023 21:08:29 +0200 Subject: [PATCH 3/8] Added definitions --- kernelspec-spec/kernelspec.schema.json | 95 ++++++++++++++++++++------ 1 file changed, 73 insertions(+), 22 deletions(-) diff --git a/kernelspec-spec/kernelspec.schema.json b/kernelspec-spec/kernelspec.schema.json index d959ee5d..11f055fb 100644 --- a/kernelspec-spec/kernelspec.schema.json +++ b/kernelspec-spec/kernelspec.schema.json @@ -1,47 +1,98 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.jupyter.org/kernelspec-v1.0.schema.json", + "$id": "https://schema.jupyter.org/kernelspec-v1.0.schema.json", "title": "Jupyter Kernelspec", "description": "A description of the data required to start and manage a Jupyter Kernel", "type": "object", - "properties": { + "definitions": { "argv": { - "description": "A list of command line arguments used to start the kernel. The text {connection_file} in any argument will be replaced with the path to the connection file.", - "type": "array", - "items": { - "type": "string" - }, - "minItems": 3 + "type": "object", + "required": ["argv"], + "properties": { + "argv": { + "description": "A list of command line arguments used to start the kernel. The text {connection_file} in any argument will be replaced with the path to the connection file.", + "type": "array", + "items": { + "type": "string" + }, + "minItems": 3 + } + } }, "display_name": { - "description": "The kernel’s name as it should be displayed in the UI. Unlike the kernel name used in the API, this can contain arbitrary unicode characters.", - "type": "string" + "type": "object", + "required": ["display_name"], + "properties": { + "display_name": { + "description": "The kernel’s name as it should be displayed in the UI. Unlike the kernel name used in the API, this can contain arbitrary unicode characters.", + "type": "string" + } + } }, "language": { - "description": "The name of the language of the kernel. When loading notebooks, if no matching kernelspec key (may differ across machines) is found, a kernel with a matching language will be used. This allows a notebook written on any Python or Julia kernel to be properly associated with the user’s Python or Julia kernel, even if they aren’t listed under the same name as the author’s.", - "type": "string" + "type": "object", + "required": ["language"], + "properties": { + "language": { + "description": "The name of the language of the kernel. When loading notebooks, if no matching kernelspec key (may differ across machines) is found, a kernel with a matching language will be used. This allows a notebook written on any Python or Julia kernel to be properly associated with the user’s Python or Julia kernel, even if they aren’t listed under the same name as the author’s.", + "type": "string" + } + } }, "kernel_protocol_version": { - "description": "The version of protocol this kernel implements. If not specified, the client will assume the version is <5.5 until it can get it via the kernel_info request. The kernel protocol uses semantic versioning (SemVer).", - "type": "string", - "pattern": "^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$" + "type": "object", + "required": ["kernel_protocol_version"], + "properties": { + "kernel_protocol_version": { + "description": "The version of protocol this kernel implements. If not specified, the client will assume the version is <5.5 until it can get it via the kernel_info request. The kernel protocol uses semantic versioning (SemVer).", + "type": "string", + "pattern": "^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$" + } + } }, "interrupt_mode": { - "description": "May be either signal or message and specifies how a client is supposed to interrupt cell execution on this kernel, either by sending an interrupt signal via the operating system’s signalling facilities (e.g. SIGINT on POSIX systems), or by sending an interrupt_request message on the control channel (see Kernel interrupt). If this is not specified the client will default to signal mode.", - "type": "string", - "enum": ["signal", "message"] + "type": "object", + "required": ["interrupt_mode"], + "properties": { + "interrupt_mode": { + "description": "May be either signal or message and specifies how a client is supposed to interrupt cell execution on this kernel, either by sending an interrupt signal via the operating system’s signalling facilities (e.g. SIGINT on POSIX systems), or by sending an interrupt_request message on the control channel (see Kernel interrupt). If this is not specified the client will default to signal mode.", + "type": "string", + "enum": ["signal", "message"] + } + } }, "env": { - "description": "A dictionary of environment variables to set for the kernel. These will be added to the current environment variables before the kernel is started. Existing environment variables can be referenced using ${} and will be substituted with the corresponding value. Administrators should note that use of ${} can expose sensitive variables and should use only in controlled circumstances.", "type": "object", - "additionalProperties": {"type": "string" } + "required": ["env"], + "properties": { + "env": { + "description": "A dictionary of environment variables to set for the kernel. These will be added to the current environment variables before the kernel is started. Existing environment variables can be referenced using ${} and will be substituted with the corresponding value. Administrators should note that use of ${} can expose sensitive variables and should use only in controlled circumstances.", + "type": "object", + "additionalProperties": {"type": "string" } + } + } }, "metadata": { - "description": "A dictionary of additional attributes about this kernel; used by clients to aid in kernel selection. Metadata added here should be namespaced for the tool reading and writing that metadata.", "type": "object", - "additionalProperties": {"type": "object"} + "required": ["metadata"], + "properties": { + "metadata": { + "description": "A dictionary of additional attributes about this kernel; used by clients to aid in kernel selection. Metadata added here should be namespaced for the tool reading and writing that metadata.", + "type": "object", + "additionalProperties": {"type": "object"} + } + } } }, + "anyOf": [ + { "$ref": "#/definitions/argv" }, + { "$ref": "#/definitions/display_name" }, + { "$ref": "#/definitions/language" }, + { "$ref": "#/definitions/kernel_protocol_version" }, + { "$ref": "#/definitions/interrupt_mode" }, + { "$ref": "#/definitions/env" }, + { "$ref": "#/definitions/metadata" } + ], "required": ["argv", "display_name", "language"] } From a55d6ed7f5a6507434239499c9f8417b1152b7ff Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Thu, 11 May 2023 11:43:17 +0200 Subject: [PATCH 4/8] Minor changes according to last SSC discussions --- kernelspec-spec/kernelspec-spec.md | 2 +- kernelspec-spec/kernelspec.schema.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/kernelspec-spec/kernelspec-spec.md b/kernelspec-spec/kernelspec-spec.md index efcf35d6..4bab9ab8 100644 --- a/kernelspec-spec/kernelspec-spec.md +++ b/kernelspec-spec/kernelspec-spec.md @@ -18,7 +18,7 @@ We propose to specify the kernelspec with the JSON schema joined in this PR. The [the current description of the kernelspec](https://jupyter-client.readthedocs.io/en/stable/kernels.html#kernel-specs), and adds an optional `kernel_protocol_version` field. -The specification and the documentation of the kernelspec will be stored aside [those of the kernel protocol](https://github.com/jupyter-standards/kernel-protocol) +The documentation of the kernelspec will be stored aside [that of the kernel protocol](https://github.com/jupyter-standards/kernel-protocol). The schema will be stored in a dedicated repo for all Jupyter schemas. ### Impact on existing implementations diff --git a/kernelspec-spec/kernelspec.schema.json b/kernelspec-spec/kernelspec.schema.json index 11f055fb..83f577f5 100644 --- a/kernelspec-spec/kernelspec.schema.json +++ b/kernelspec-spec/kernelspec.schema.json @@ -6,7 +6,7 @@ "type": "object", "definitions": { - "argv": { + "kernel_arguments": { "type": "object", "required": ["argv"], "properties": { From ac52496c09f35b1fe4c1c4e97da7c5691a84ec94 Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Mon, 26 Feb 2024 21:27:23 +0100 Subject: [PATCH 5/8] Update kernelspec-spec/kernelspec-spec.md Co-authored-by: Jason Grout --- kernelspec-spec/kernelspec-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/kernelspec-spec/kernelspec-spec.md b/kernelspec-spec/kernelspec-spec.md index 4bab9ab8..994b30b1 100644 --- a/kernelspec-spec/kernelspec-spec.md +++ b/kernelspec-spec/kernelspec-spec.md @@ -2,7 +2,7 @@ title: kernelspec specification authors: Johan Mabille issue-number: XX -pr-number: XX +pr-number: [#105](https://github.com/jupyter/enhancement-proposals/pull/105) date-started: "2023-04-19" --- From 85949fd1b1e5b0873e5e80cc33ff775b82e70cb3 Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Mon, 26 Feb 2024 21:27:49 +0100 Subject: [PATCH 6/8] Update kernelspec-spec/kernelspec.schema.json MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Frédéric Collonval --- kernelspec-spec/kernelspec.schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/kernelspec-spec/kernelspec.schema.json b/kernelspec-spec/kernelspec.schema.json index 83f577f5..2a3ca59a 100644 --- a/kernelspec-spec/kernelspec.schema.json +++ b/kernelspec-spec/kernelspec.schema.json @@ -47,7 +47,7 @@ "kernel_protocol_version": { "description": "The version of protocol this kernel implements. If not specified, the client will assume the version is <5.5 until it can get it via the kernel_info request. The kernel protocol uses semantic versioning (SemVer).", "type": "string", - "pattern": "^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$" + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$" } } }, From 16e52a8d6d166a23f4bb90fac23b7d16e564aa7b Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Mon, 26 Feb 2024 21:39:48 +0100 Subject: [PATCH 7/8] Added link to the Jupyter schema repo --- kernelspec-spec/kernelspec-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/kernelspec-spec/kernelspec-spec.md b/kernelspec-spec/kernelspec-spec.md index 994b30b1..4d9f3ad9 100644 --- a/kernelspec-spec/kernelspec-spec.md +++ b/kernelspec-spec/kernelspec-spec.md @@ -18,7 +18,7 @@ We propose to specify the kernelspec with the JSON schema joined in this PR. The [the current description of the kernelspec](https://jupyter-client.readthedocs.io/en/stable/kernels.html#kernel-specs), and adds an optional `kernel_protocol_version` field. -The documentation of the kernelspec will be stored aside [that of the kernel protocol](https://github.com/jupyter-standards/kernel-protocol). The schema will be stored in a dedicated repo for all Jupyter schemas. +The documentation of the kernelspec will be stored aside [that of the kernel protocol](https://github.com/jupyter-standards/kernel-protocol). The schema will be stored in the [dedicated repo for all Jupyter schemas](https://github.com/jupyter/schema). ### Impact on existing implementations From 6c9be20f1fad9304f126dafef814e61db38a944b Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Mon, 13 May 2024 23:31:38 +0200 Subject: [PATCH 8/8] Updated minimal number of arguments --- kernelspec-spec/kernelspec.schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/kernelspec-spec/kernelspec.schema.json b/kernelspec-spec/kernelspec.schema.json index 2a3ca59a..3f682027 100644 --- a/kernelspec-spec/kernelspec.schema.json +++ b/kernelspec-spec/kernelspec.schema.json @@ -16,7 +16,7 @@ "items": { "type": "string" }, - "minItems": 3 + "minItems": 1 } } },