You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Split library descriptors into separate jsons
* Load local library descriptors from "/.jupyter_kotlin/libraries" directory
* Asynchronously download library descriptors from master branch of "https://github.com/Kotlin/kotlin-jupyter" repository
* Cache downloaded descriptors in "/.jupyter_kotlin/cache/libraries" directory
* Check library descriptor format version and suggest updating kernel if format was changed
-[kmath](https://github.com/mipt-npm/kmath) - Kotlin mathematical library analogous to NumPy
90
90
91
-
*The list of all supported libraries can be found in [config file](config.json)*
91
+
*The list of all supported libraries can be found in ['libraries' directory](libraries)*
92
92
93
93
A definition of supported library may have a list of optional arguments that can be overriden when library is included.
94
94
The major use case for library arguments is to specify particular version of library. Most library definitions default to `-SNAPSHOT` version that may be overriden in `%use` magic.
@@ -127,14 +127,14 @@ Press `TAB` to get the list of suggested items for completion.
127
127
2. Run `jupyter-notebook`
128
128
3. Attach remote debugger to JVM with specified port
129
129
130
-
## Contributing
130
+
## Adding new libraries
131
131
132
-
### Support new libraries
132
+
To support new `JVM` library and make it available via `%use` magic command you need to create a library descriptor for it.
133
133
134
-
You are welcome to add support for new `Kotlin` libraries by contributing to [config.json](config.json) file.
134
+
Check ['libraries'](libraries) directory to see examples of library descriptors.
135
135
136
-
Library descriptor has the following fields:
137
-
-`name`: short name of the library with optional arguments. All library arguments must have default value specified. Syntax: `<name>(<arg1>=<default1>, <arg2>=<default2>)`
136
+
Library descriptor is a `<libName>.json` file with the following fields:
137
+
-`properties`: a dictionary of properties that are used within library descriptor
138
138
-`link`: a link to library homepage. This link will be displayed in `:help` command
139
139
-`repositories`: a list of maven or ivy repositories to search for dependencies
140
140
-`dependencies`: a list of library dependencies
@@ -143,8 +143,26 @@ Library descriptor has the following fields:
143
143
-`initCell`: a list of code snippets to be executed before execution of any cell
144
144
-`renderers`: a list of type converters for special rendering of particular types
145
145
146
+
*All fields are optional
147
+
146
148
Fields for type renderer:
147
149
-`class`: fully-qualified class name for the type to be rendered
148
-
-`result`: expression to produce output value. Source object is referenced as `$it`
150
+
-`result`: expression that produces output value. Source object is referenced as `$it`
151
+
152
+
Name of the file is a library name that is passed to '%use' command
153
+
154
+
Library properties can be used in any parts of library descriptor as `$property`
155
+
156
+
To register new library descriptor:
157
+
1. For private usage - add it to local settings folder `<UserHome>/.jupyter_kotlin/libraries`
158
+
2. For sharing with community - commit it to ['libraries'](libraries) directory and create pull request.
159
+
160
+
If you are maintaining some library and want to update your library descriptor, just create pull request with your update. After your request is accepted,
161
+
new version of your library will be available to all Kotlin Jupyter users immediately on next kernel startup (no kernel update is needed).
162
+
163
+
If a library descriptor with the same name is found in several locations, the following resolution priority is used:
164
+
1. Local settings folder (highest priority)
165
+
2.['libraries'](libraries) folder at the latest master branch of `https://github.com/Kotlin/kotlin-jupyter` repository
166
+
3. Kernel installation directory
149
167
150
-
Library arguments can be referenced in any parts of library descriptor as `$arg`
168
+
If you don't want some library to be updated automatically, put fixed version of its library descriptor into local settings folder.
val url ="$GitHubApiPrefix/contents/$LibrariesDir/$LibraryPropertiesFile?ref=$commitSha"
131
+
log.info("Checking current library descriptor format version from $url")
132
+
val response = getHttp(url)
133
+
val downloadUrl = response.jsonObject["download_url"].toString()
134
+
val downloadResult = getHttp(downloadUrl)
135
+
val result = downloadResult.text.parseIniConfig()["formatVersion"]!!.toInt()
136
+
log.info("Current library descriptor format version: $result")
137
+
result
138
+
}
139
+
140
+
/***
141
+
* Downloads library descriptors from GitHub to local cache if new commits in `libraries` directory were detected
142
+
*/
143
+
fundownloadNewLibraryDescriptors() {
144
+
145
+
// Read commit hash and timestamp for locally cached libraries.
146
+
// Timestamp is used as parameter for commits request to reduce output
147
+
148
+
val footprintFilePath =Paths.get(LocalSettingsPath, LocalCacheDir, CachedLibrariesFootprintFile).toString()
149
+
log.info("Reading commit info for which library descriptors were cached: '$footprintFilePath'")
150
+
val footprintFile =File(footprintFilePath)
151
+
val footprint = footprintFile.tryReadIniConfig()
152
+
val timestampRegex ="""\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z""".toRegex()
153
+
val syncedCommitTimestamp = footprint?.get("timestamp")?.validOrNull { timestampRegex.matches(it) }
154
+
val syncedCommitSha = footprint?.get("sha")
155
+
log.info("Local libraries are cached for commit '$syncedCommitSha' at '$syncedCommitTimestamp'")
156
+
157
+
val (latestCommitSha, latestCommitTimestamp) = getLatestCommitToLibraries(syncedCommitTimestamp) ?:return
158
+
if (latestCommitSha.equals(syncedCommitSha)) {
159
+
log.info("No new commits to library descriptors were detected")
160
+
return
161
+
}
162
+
163
+
// Download library descriptor version
164
+
165
+
val descriptorVersion = getLibraryDescriptorVersion(latestCommitSha) ?:return
166
+
if (descriptorVersion != libraryDescriptorFormatVersion) {
167
+
if (descriptorVersion < libraryDescriptorFormatVersion)
168
+
log.error("Incorrect library descriptor version in GitHub repository: $descriptorVersion")
169
+
else
170
+
log.warn("Kotlin Kernel needs to be updated to the latest version. Couldn't download new library descriptors from GitHub repository because their format was changed")
171
+
return
172
+
}
173
+
174
+
// Download library descriptors
175
+
176
+
log.info("New commits to library descriptors were detected. Downloading library descriptors for commit $latestCommitSha")
177
+
178
+
val libraries = log.catchAll {
179
+
val url ="$GitHubApiPrefix/contents/$LibrariesDir?ref=$latestCommitSha"
180
+
log.info("Requesting the list of library descriptors at $url")
181
+
val response = getHttp(url)
182
+
val filenameRegex ="""[\w.-]+\.$LibraryDescriptorExt""".toRegex()
183
+
184
+
response.jsonArray.mapNotNull {
185
+
val o = it asJSONObject
186
+
val filename = o["name"] asString
187
+
if (filenameRegex.matches(filename)) {
188
+
val libUrl = o["download_url"].toString()
189
+
log.info("Downloading '$filename' from $libUrl")
190
+
val res = getHttp(libUrl)
191
+
val text = res.jsonObject.toString()
192
+
filename to text
193
+
} elsenull
194
+
}
195
+
} ?:return
196
+
197
+
// Save library descriptors to local cache
198
+
199
+
val librariesPath =Paths.get(LocalSettingsPath, LocalCacheDir, LibrariesDir)
200
+
val librariesDir = librariesPath.toFile()
201
+
log.info("Saving ${libraries.count()} library descriptors to local cache at '$librariesPath'")
0 commit comments