[ENG-1368] add ability to add snippet to top of Python SDK README.md

generator/konfig-dash/.changeset/selfish-ads-rest.md

@@ -0,0 +1,7 @@
+---
+'konfig-openapi-spec': minor
+'konfig-cli': minor
+'konfig-lib': minor
+---
+
+add readmeHeaderSnippet configuration

generator/konfig-dash/api/src/functions/formatPython/formatPython.ts

@@ -1,6 +1,6 @@
 import type { APIGatewayEvent, Context } from 'aws-lambda'
 import { urlForBlackdApi } from 'src/lib/urlForBlackdApi'
-import axios from 'axios'
+import axios, { AxiosError } from 'axios'
 import {
   CORS_HEADERS_METHOD_HEADERS,
   CORS_HEADERS_ORIGIN,
@@ -30,22 +30,35 @@ export const handler = async (event: APIGatewayEvent, context: Context) => {
     }
   }
   if (event.body === null) throw Error('Missing Request body')
-  const { data: formattedSource } = await axios.post(
-    urlForBlackdApi(),
-    event.body
-  )
+  try {
+    const { data: formattedSource } = await axios.post(
+      urlForBlackdApi(),
+      event.body
+    )
 
-  return {
-    statusCode: 200,
-    headers: {
-      ...CORS_HEADERS_ORIGIN,
-      'Content-Type': 'text/plain',
-    },
-    // For some reason blackd returns an empty string if the
-    // code snippet is already formatted so we have to handle
-    // that edge case with an empty string check
-    // From: https://black.readthedocs.io/en/stable/usage_and_configuration/black_as_a_server.html
-    // "HTTP 204: If the input is already well-formatted. The response body is empty."
-    body: formattedSource == '' ? event.body : formattedSource,
+    return {
+      statusCode: 200,
+      headers: {
+        ...CORS_HEADERS_ORIGIN,
+        'Content-Type': 'text/plain',
+      },
+      // For some reason blackd returns an empty string if the
+      // code snippet is already formatted so we have to handle
+      // that edge case with an empty string check
+      // From: https://black.readthedocs.io/en/stable/usage_and_configuration/black_as_a_server.html
+      // "HTTP 204: If the input is already well-formatted. The response body is empty."
+      body: formattedSource == '' ? event.body : formattedSource,
+    }
+  } catch (e) {
+    if (e instanceof AxiosError) {
+      return {
+        statusCode: 500,
+        headers: {
+          ...CORS_HEADERS_ORIGIN,
+          'Content-Type': 'text/plain',
+        },
+        body: event.body,
+      }
+    }
   }
 }

generator/konfig-dash/api/src/lib/prepare-java-request-properties.ts

@@ -14,9 +14,16 @@ import {
  * Now all thats necessary to give the Java Generator more context is:
  *
  * 1. Modify the AdditionalProperties schema in the Java API's OpenAPI specification at api.yaml
- * 2. Run generate-models.sh
- * 3. Make updates to KonfigYaml.ts / KonfigYamlCommon.ts
- * 4. Extract data from body and return as a key-value pair in the properties object
+ *    (file located at: [KONFIG REPO]/misc/openapi-generator-configs/openapi-generator-api/api.yaml)
+ * 2. Update JavaGenerateApiRequestBody.ts file with same changes as api.yaml
+ * 3. Run generate-models.sh
+ *    (file located at: [KONFIG REPO]/misc/openapi-generator-configs/openapi-generator-api/generate-models.sh)
+ * 4. Make updates to KonfigYaml.ts / KonfigYamlCommon.ts
+ * 5. Extract data from body and return as a key-value pair in the properties object (in this function implementation)
+ *
+ * Note: If you are adding a configuration that points to a file like "readmeHeaderSnippet", you need to add code to
+ * "/generator/konfig-dash/packages/konfig-cli/src/commands/generate.ts" to read the file contents and send the contents
+ * to the generator api instead.
  */
 export function prepareJavaRequestProperties({
   body,
@@ -42,6 +49,10 @@ export function prepareJavaRequestProperties({
     properties['gitRepoName'] = git.repoName
   }
 
+  if ('readmeHeaderSnippet' in generatorConfig) {
+    properties['readmeHeaderSnippet'] = generatorConfig.readmeHeaderSnippet
+  }
+
   if ('outputDirectory' in generatorConfig) {
     properties['outputDirectory'] = generatorConfig.outputDirectory
   }

generator/konfig-dash/packages/konfig-cli/src/commands/generate.ts

@@ -20,7 +20,7 @@ import {
   GeneratorGitConfig,
 } from 'konfig-lib'
 import globby from 'globby'
-import { Konfig } from 'konfig-typescript-sdk'
+import { Konfig, KonfigError } from 'konfig-typescript-sdk'
 import * as fs from 'fs-extra'
 import axios, { AxiosError } from 'axios'
 import * as os from 'os'
@@ -52,6 +52,7 @@ import { isSubmodule } from '../util/is-submodule'
 import { getHostForGenerateApi } from '../util/get-host-for-generate-api'
 import { getSdkDefaultBranch } from '../util/get-sdk-default-branch'
 import { insertTableOfContents } from '../util/insert-table-of-contents'
+import boxen from 'boxen'
 
 function getOutputDir(
   outputFlag: string | undefined,
@@ -1166,22 +1167,7 @@ export default class Deploy extends Command {
               ])
               for (const markdownPath of markdownFiles) {
                 const markdown = fs.readFileSync(markdownPath, 'utf-8')
-                const pythonSnippetRegex =
-                  // rewrite the following regex to not include "```" in the match
-                  /\`\`\`python\r?\n([\s\S]*?)\r?\n\`\`\`/g
-
-                // find all code snippets in the markdown string that matches typescriptSnippetRegex
-                // and format them and replace the code snippets with the formatted code snippets
-                const formattedMarkdown = await replaceAsync(
-                  markdown,
-                  pythonSnippetRegex,
-                  async (_, codeSnippet) => {
-                    const { data: formattedCodeSnippet } =
-                      await konfig.sdk.formatPython(codeSnippet)
-                    return '```python\n' + formattedCodeSnippet + '```'
-                  }
-                )
-                fs.writeFileSync(markdownPath, formattedMarkdown)
+                await formatPythonSnippet({ markdown, markdownPath, konfig })
               }
 
               CliUx.ux.action.stop()
@@ -1415,11 +1401,17 @@ function handleReadmeSnippet<
   C extends object & {
     readmeSnippet?: string
     asyncReadmeSnippet?: string
+    readmeHeaderSnippet?: string
     readmeDescriptionSnippet?: string
   }
 >({ config }: { config: C }): C {
   if (config.readmeSnippet !== undefined)
     config.readmeSnippet = fs.readFileSync(config.readmeSnippet, 'utf-8')
+  if (config.readmeHeaderSnippet !== undefined)
+    config.readmeHeaderSnippet = fs.readFileSync(
+      config.readmeHeaderSnippet,
+      'utf-8'
+    )
   if (config.asyncReadmeSnippet !== undefined)
     config.asyncReadmeSnippet = fs.readFileSync(
       config.asyncReadmeSnippet,
@@ -1564,6 +1556,60 @@ function constructGoGenerationRequest({
   return requestGo
 }
 
+async function formatPythonSnippet({
+  markdown,
+  markdownPath,
+  konfig,
+}: {
+  konfig: Konfig
+  markdownPath: string
+  markdown: string
+}) {
+  const pythonSnippetRegex = /\`\`\`python\r?\n([\s\S]*?)\r?\n\`\`\`/g
+
+  // find all code snippets in the markdown string that matches typescriptSnippetRegex
+  // and format them and replace the code snippets with the formatted code snippets
+  try {
+    const formattedMarkdown = await replaceAsync(
+      markdown,
+      pythonSnippetRegex,
+      async (match, codeSnippet, offset) => {
+        // Check if the block is preceded by a line ending with '>'
+        const blockStartIndex = offset - 1
+        const startOfLineIndex =
+          markdown.lastIndexOf('\n', blockStartIndex - 1) + 1
+        const lineBeforeBlock = markdown.substring(
+          startOfLineIndex,
+          blockStartIndex
+        )
+
+        if (lineBeforeBlock.endsWith('>')) {
+          // If it is, we leave the match unaltered
+          return match
+        } else {
+          // If it's not, proceed with formatting
+          const { data: formattedCodeSnippet } = await konfig.sdk.formatPython(
+            codeSnippet
+          )
+          return '```python\n' + formattedCodeSnippet + '```'
+        }
+      }
+    )
+    fs.writeFileSync(markdownPath, formattedMarkdown)
+  } catch (e) {
+    if (e instanceof KonfigError)
+      if (typeof e.responseBody === 'string') {
+        console.log(
+          boxen(e.responseBody, {
+            title: "Warning: Couldn't format Python code snippet",
+            titleAlignment: 'center',
+            borderColor: 'yellow',
+          })
+        )
+      }
+  }
+}
+
 function constructPhpGenerationRequest({
   configDir,
   phpGeneratorConfig,

generator/konfig-dash/packages/konfig-lib/src/JavaGenerateApiRequestBody.ts

@@ -3,6 +3,7 @@ import { z } from './zod'
 import { TemplateFiles } from './TemplateFiles'
 import {
   clientStateWithExamples,
+  readmeHeaderSnippet,
   topLevelOperationsOrderedSchema,
 } from './KonfigYaml'
 import { tagPrioritySchema } from './KonfigYamlCommon'
@@ -11,6 +12,7 @@ const additionalProperties = z
   .object({
     useDescriptionInOperationTableDocumentation: z.boolean().optional(),
     apiPackage: z.string().optional(),
+    readmeHeaderSnippet: readmeHeaderSnippet,
     artifactId: z.string().optional(),
     artifactUrl: z.string().optional(),
     authorEmail: z.string().describe('[email protected]').optional(),

generator/konfig-dash/packages/konfig-lib/src/KonfigYaml.ts

@@ -198,8 +198,16 @@ export const pythonResponseTypeVersion = z
     "Choose which version of Konfig's implementation of responses for the Python SDK to use."
   )
 
+export const readmeHeaderSnippet = z
+  .string()
+  .optional()
+  .describe(
+    'A snippet of markdown that will be inserted at the top of the README.md file. This is useful for adding a custom header to the README.md file that is not generated by Konfig.'
+  )
+
 export const pythonConfig = z.object({
   useDescriptionInOperationTableDocumentation,
+  readmeHeaderSnippet,
   language: z.literal('python').default('python'),
   packageName: z.string().describe('acme_client'),
   projectName: z.string().describe('acme-python-sdk'),

generator/konfig-dash/packages/konfig-openapi-spec/openapi.yaml

@@ -539,6 +539,11 @@ components:
                   type: boolean
                   description: Whether or not to use the operation's description in the operation
                     table documentation. By default the summary is used.
+                readmeHeaderSnippet:
+                  type: string
+                  description: A snippet of markdown that will be inserted at the top of the
+                    README.md file. This is useful for adding a custom header to
+                    the README.md file that is not generated by Konfig.
                 language:
                   type: string
                   enum:
@@ -2215,6 +2220,11 @@ components:
                     type: boolean
                     description: Whether or not to use the operation's description in the operation
                       table documentation. By default the summary is used.
+                  readmeHeaderSnippet:
+                    type: string
+                    description: A snippet of markdown that will be inserted at the top of the
+                      README.md file. This is useful for adding a custom header
+                      to the README.md file that is not generated by Konfig.
                   language:
                     type: string
                     enum:

generator/konfig-generator-api/src/main/java/com/konfigthis/api/GenerateApi.java

@@ -324,6 +324,7 @@ default Map<String, Object> transformAdditionalPropertiesToMap(AdditionalPropert
         putIfPresent(map, "swiftPackagePath", additionalProperties.getSwiftPackagePath());
         putIfPresent(map, "apiDocumentationAuthenticationPartial", additionalProperties.getApiDocumentationAuthenticationPartial());
         putIfPresent(map, "readmeSnippet", additionalProperties.getReadmeSnippet());
+        putIfPresent(map, "readmeHeaderSnippet", additionalProperties.getReadmeHeaderSnippet());
         putIfPresent(map, "asyncReadmeSnippet", additionalProperties.getAsyncReadmeSnippet());
         putIfPresent(map, "readmeSupportingDescriptionSnippet", additionalProperties.getReadmeSupportingDescriptionSnippet());
         putIfPresent(map, "readmeDescriptionSnippet", additionalProperties.getReadmeDescriptionSnippet());

generator/konfig-generator-api/src/main/java/com/konfigthis/model/AdditionalProperties.java

@@ -223,6 +223,9 @@ public class AdditionalProperties {
   @JsonProperty("readmeSnippet")
   private String readmeSnippet;
 
+  @JsonProperty("readmeHeaderSnippet")
+  private String readmeHeaderSnippet;
+
   @JsonProperty("asyncReadmeSnippet")
   private String asyncReadmeSnippet;
 
@@ -1468,6 +1471,25 @@ public void setReadmeSnippet(String readmeSnippet) {
     this.readmeSnippet = readmeSnippet;
   }
 
+  public AdditionalProperties readmeHeaderSnippet(String readmeHeaderSnippet) {
+    this.readmeHeaderSnippet = readmeHeaderSnippet;
+    return this;
+  }
+
+  /**
+   * Get readmeHeaderSnippet
+   * @return readmeHeaderSnippet
+  */
+
+  @Schema(name = "readmeHeaderSnippet", required = false)
+  public String getReadmeHeaderSnippet() {
+    return readmeHeaderSnippet;
+  }
+
+  public void setReadmeHeaderSnippet(String readmeHeaderSnippet) {
+    this.readmeHeaderSnippet = readmeHeaderSnippet;
+  }
+
   public AdditionalProperties asyncReadmeSnippet(String asyncReadmeSnippet) {
     this.asyncReadmeSnippet = asyncReadmeSnippet;
     return this;
@@ -1697,6 +1719,7 @@ public boolean equals(Object o) {
         Objects.equals(this.userAgent, additionalProperties.userAgent) &&
         Objects.equals(this.npmName, additionalProperties.npmName) &&
         Objects.equals(this.readmeSnippet, additionalProperties.readmeSnippet) &&
+        Objects.equals(this.readmeHeaderSnippet, additionalProperties.readmeHeaderSnippet) &&
         Objects.equals(this.asyncReadmeSnippet, additionalProperties.asyncReadmeSnippet) &&
         Objects.equals(this.readmeSupportingDescriptionSnippet, additionalProperties.readmeSupportingDescriptionSnippet) &&
         Objects.equals(this.readmeDescriptionSnippet, additionalProperties.readmeDescriptionSnippet) &&
@@ -1708,7 +1731,7 @@ public boolean equals(Object o) {
 
   @Override
   public int hashCode() {
-    return Objects.hash(objectPropertyNamingConvention, dependencies, readmeHeader, isGitSubmodule, gitDefaultBranch, gitRepoName, clientName, pubName, pubLibrary, pubDescription, pubAuthor, pythonResponseTypeVersion, pubAuthorEmail, pubHomepage, pubPublishTo, pubRepository, pubVersion, readmeOperation, moduleName, gitLabProjectId, outputDirectory, topLevelOperations, omitInfoDescription, omitModelDocumentation, omitApiDocumentation, useSecurityKeyParamNameAsPropertyName, tagPriority, useDescriptionInOperationTableDocumentation, setSkipSerializationToTrueByDefault, includeFetchAdapter, packagistUsername, toStringReturnsJson, includeEventSourceParser, keepAllParametersOptional, apiDocumentationAuthenticationPartial, composerPackageName, defaultTimeout, supportPhp7, useSingleRequestParameter, artifactUrl, artifactId, groupId, invokerPackage, modelPackage, apiPackage, projectName, podVersion, removeKonfigBranding, podName, classPrefix, authorName, authorEmail, podAuthors, swiftPackagePath, disallowAdditionalPropertiesIfNotPresent, packageVersion, packageUrl, npmVersion, gemName, gemVersion, userAgent, npmName, readmeSnippet, asyncReadmeSnippet, readmeSupportingDescriptionSnippet, readmeDescriptionSnippet, apiKeyAlias, clientState, clientStateWithExamples, clientStateIsOptional);
+    return Objects.hash(objectPropertyNamingConvention, dependencies, readmeHeader, isGitSubmodule, gitDefaultBranch, gitRepoName, clientName, pubName, pubLibrary, pubDescription, pubAuthor, pythonResponseTypeVersion, pubAuthorEmail, pubHomepage, pubPublishTo, pubRepository, pubVersion, readmeOperation, moduleName, gitLabProjectId, outputDirectory, topLevelOperations, omitInfoDescription, omitModelDocumentation, omitApiDocumentation, useSecurityKeyParamNameAsPropertyName, tagPriority, useDescriptionInOperationTableDocumentation, setSkipSerializationToTrueByDefault, includeFetchAdapter, packagistUsername, toStringReturnsJson, includeEventSourceParser, keepAllParametersOptional, apiDocumentationAuthenticationPartial, composerPackageName, defaultTimeout, supportPhp7, useSingleRequestParameter, artifactUrl, artifactId, groupId, invokerPackage, modelPackage, apiPackage, projectName, podVersion, removeKonfigBranding, podName, classPrefix, authorName, authorEmail, podAuthors, swiftPackagePath, disallowAdditionalPropertiesIfNotPresent, packageVersion, packageUrl, npmVersion, gemName, gemVersion, userAgent, npmName, readmeSnippet, readmeHeaderSnippet, asyncReadmeSnippet, readmeSupportingDescriptionSnippet, readmeDescriptionSnippet, apiKeyAlias, clientState, clientStateWithExamples, clientStateIsOptional);
   }
 
   @Override
@@ -1778,6 +1801,7 @@ public String toString() {
     sb.append("    userAgent: ").append(toIndentedString(userAgent)).append("\n");
     sb.append("    npmName: ").append(toIndentedString(npmName)).append("\n");
     sb.append("    readmeSnippet: ").append(toIndentedString(readmeSnippet)).append("\n");
+    sb.append("    readmeHeaderSnippet: ").append(toIndentedString(readmeHeaderSnippet)).append("\n");
     sb.append("    asyncReadmeSnippet: ").append(toIndentedString(asyncReadmeSnippet)).append("\n");
     sb.append("    readmeSupportingDescriptionSnippet: ").append(toIndentedString(readmeSupportingDescriptionSnippet)).append("\n");
     sb.append("    readmeDescriptionSnippet: ").append(toIndentedString(readmeDescriptionSnippet)).append("\n");

generator/konfig-generator-api/src/main/resources/python/README.handlebars

@@ -19,6 +19,10 @@
 
 {{> readme_badges}}
 {{/if}}
+{{#if readmeHeaderSnippet}}
+
+{{{readmeHeaderSnippet}}}
+{{/if}}
 
 ## Table of Contents
 

generator/konfig-integration-tests/sdks/python-readme-header-snippet/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2023- Konfig, Inc. (https://konfigthis.com)
+
+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.

generator/konfig-integration-tests/sdks/python-readme-header-snippet/README.md

@@ -0,0 +1,5 @@
+# konfig
+
+|Language|Version|Package Manager|Documentation|Source|
+|-|-|-|-|-|
+|Python|1.0.0-beta.1|[PyPI](https://pypi.org/project/python-readme-header-snippet/1.0.0-beta.1)|[Documentation](https://github.com/konfig-dev/konfig/tree/main/python/README.md)|[Source](https://github.com/konfig-dev/konfig/tree/main/python)|