picata 0.0.6__py3-none-any.whl → 0.0.7__py3-none-any.whl

node_modules/jackspeak/README.md

@@ -0,0 +1,357 @@
+# jackspeak
+
+A very strict and proper argument parser.
+
+Validate string, boolean, and number options, from the command
+line and the environment.
+
+Call the `jack` method with a config object, and then chain
+methods off of it.
+
+At the end, call the `.parse()` method, and you'll get an object
+with `positionals` and `values` members.
+
+Any unrecognized configs or invalid values will throw an error.
+
+As long as you define configs using object literals, types will
+be properly inferred and TypeScript will know what kinds of
+things you got.
+
+If you give it a prefix for environment variables, then defaults
+will be read from the environment, and parsed values written back
+to it, so you can easily pass configs through to child processes.
+
+Automatically generates a `usage`/`help` banner by calling the
+`.usage()` method.
+
+Unless otherwise noted, all methods return the object itself.
+
+## USAGE
+
+```js
+import { jack } from 'jackspeak'
+// this works too:
+// const { jack } = require('jackspeak')
+
+const { positionals, values } = jack({ envPrefix: 'FOO' })
+  .flag({
+    asdf: { description: 'sets the asfd flag', short: 'a', default: true },
+    'no-asdf': { description: 'unsets the asdf flag', short: 'A' },
+    foo: { description: 'another boolean', short: 'f' },
+  })
+  .optList({
+    'ip-addrs': {
+      description: 'addresses to ip things',
+      delim: ',', // defaults to '\n'
+      default: ['127.0.0.1'],
+    },
+  })
+  .parse([
+    'some',
+    'positional',
+    '--ip-addrs',
+    '192.168.0.1',
+    '--ip-addrs',
+    '1.1.1.1',
+    'args',
+    '--foo', // sets the foo flag
+    '-A', // short for --no-asdf, sets asdf flag to false
+  ])
+
+console.log(process.env.FOO_ASDF) // '0'
+console.log(process.env.FOO_FOO) // '1'
+console.log(values) // {
+//   'ip-addrs': ['192.168.0.1', '1.1.1.1'],
+//   foo: true,
+//   asdf: false,
+// }
+console.log(process.env.FOO_IP_ADDRS) // '192.168.0.1,1.1.1.1'
+console.log(positionals) // ['some', 'positional', 'args']
+```
+
+## `jack(options: JackOptions = {}) => Jack`
+
+Returns a `Jack` object that can be used to chain and add
+field definitions. The other methods (apart from `validate()`,
+`parse()`, and `usage()` obviously) return the same Jack object,
+updated with the new types, so they can be chained together as
+shown in the code examples.
+
+Options:
+
+- `allowPositionals` Defaults to true. Set to `false` to not
+  allow any positional arguments.
+
+- `envPrefix` Set to a string to write configs to and read
+  configs from the environment. For example, if set to `MY_APP`
+  then the `foo-bar` config will default based on the value of
+  `env.MY_APP_FOO_BAR` and will write back to that when parsed.
+
+  Boolean values are written as `'1'` and `'0'`, and will be
+  treated as `true` if they're `'1'` or false otherwise.
+
+  Number values are written with their `toString()`
+  representation.
+
+  Strings are just strings.
+
+  Any value with `multiple: true` will be represented in the
+  environment split by a delimiter, which defaults to `\n`.
+
+- `env` The place to read/write environment variables. Defaults
+  to `process.env`.
+
+- `usage` A short usage string to print at the top of the help
+  banner.
+
+- `stopAtPositional` Boolean, default false. Stop parsing opts
+  and flags at the first positional argument. This is useful if
+  you want to pass certain options to subcommands, like some
+  programs do, so you can stop parsing and pass the positionals
+  to the subcommand to parse.
+
+- `stopAtPositionalTest` Conditional `stopAtPositional`. Provide
+  a function that takes a positional argument string and returns
+  boolean. If it returns `true`, then parsing will stop. Useful
+  when _some_ subcommands should parse the rest of the command
+  line options, and others should not.
+
+### `Jack.heading(text: string, level?: 1 | 2 | 3 | 4 | 5 | 6)`
+
+Define a short string heading, used in the `usage()` output.
+
+Indentation of the heading and subsequent description/config
+usage entries (up until the next heading) is set by the heading
+level.
+
+If the first usage item defined is a heading, it is always
+treated as level 1, regardless of the argument provided.
+
+Headings level 1 and 2 will have a line of padding underneath
+them. Headings level 3 through 6 will not.
+
+### `Jack.description(text: string, { pre?: boolean } = {})`
+
+Define a long string description, used in the `usage()` output.
+
+If the `pre` option is set to `true`, then whitespace will not be
+normalized. However, if any line is too long for the width
+allotted, it will still be wrapped.
+
+## Option Definitions
+
+Configs are defined by calling the appropriate field definition
+method with an object where the keys are the long option name,
+and the value defines the config.
+
+Options:
+
+- `type` Only needed for the `addFields` method, as the others
+  set it implicitly. Can be `'string'`, `'boolean'`, or
+  `'number'`.
+- `multiple` Only needed for the `addFields` method, as the
+  others set it implicitly. Set to `true` to define an array
+  type. This means that it can be set on the CLI multiple times,
+  set as an array in the `values`
+  and it is represented in the environment as a delimited string.
+- `short` A one-character shorthand for the option.
+- `description` Some words to describe what this option is and
+  why you'd set it.
+- `hint` (Only relevant for non-boolean types) The thing to show
+  in the usage output, like `--option=<hint>`
+- `validate` A function that returns false (or throws) if an
+  option value is invalid.
+- `validOptions` An array of strings or numbers that define the
+  valid values that can be set. This is not allowed on `boolean`
+  (flag) options. May be used along with a `validate()` method.
+- `default` A default value for the field. Note that this may be
+  overridden by an environment variable, if present.
+
+### `Jack.flag({ [option: string]: definition, ... })`
+
+Define one or more boolean fields.
+
+Boolean options may be set to `false` by using a
+`--no-${optionName}` argument, which will be implicitly created
+if it's not defined to be something else.
+
+If a boolean option named `no-${optionName}` with the same
+`multiple` setting is in the configuration, then that will be
+treated as a negating flag.
+
+### `Jack.flagList({ [option: string]: definition, ... })`
+
+Define one or more boolean array fields.
+
+### `Jack.num({ [option: string]: definition, ... })`
+
+Define one or more number fields. These will be set in the
+environment as a stringified number, and included in the `values`
+object as a number.
+
+### `Jack.numList({ [option: string]: definition, ... })`
+
+Define one or more number list fields. These will be set in the
+environment as a delimited set of stringified numbers, and
+included in the `values` as a number array.
+
+### `Jack.opt({ [option: string]: definition, ... })`
+
+Define one or more string option fields.
+
+### `Jack.optList({ [option: string]: definition, ... })`
+
+Define one or more string list fields.
+
+### `Jack.addFields({ [option: string]: definition, ... })`
+
+Define one or more fields of any type. Note that `type` and
+`multiple` must be set explicitly on each definition when using
+this method.
+
+## Actions
+
+Use these methods on a Jack object that's already had its config
+fields defined.
+
+### `Jack.parse(args: string[] = process.argv): { positionals: string[], values: OptionsResults }`
+
+Parse the arguments list, write to the environment if `envPrefix`
+is set, and returned the parsed values and remaining positional
+arguments.
+
+### `Jack.validate(o: any): asserts o is OptionsResults`
+
+Throws an error if the object provided is not a valid result set,
+for the configurations defined thusfar.
+
+### `Jack.usage(): string`
+
+Returns the compiled `usage` string, with all option descriptions
+and heading/description text, wrapped to the appropriate width
+for the terminal.
+
+### `Jack.setConfigValues(options: OptionsResults, src?: string)`
+
+Validate the `options` argument, and set the default value for
+each field that appears in the options.
+
+Values provided will be overridden by environment variables or
+command line arguments.
+
+### `Jack.usageMarkdown(): string`
+
+Returns the compiled `usage` string, with all option descriptions
+and heading/description text, but as markdown instead of
+formatted for a terminal, for generating HTML documentation for
+your CLI.
+
+## Some Example Code
+
+Also see [the examples
+folder](https://github.com/isaacs/jackspeak/tree/master/examples)
+
+```js
+import { jack } from 'jackspeak'
+
+const j = jack({
+  // Optional
+  // This will be auto-generated from the descriptions if not supplied
+  // top level usage line, printed by -h
+  // will be auto-generated if not specified
+  usage: 'foo [options] <files>',
+})
+  .heading('The best Foo that ever Fooed')
+  .description(
+    `
+    Executes all the files and interprets their output as
+    TAP formatted test result data.
+
+    To parse TAP data from stdin, specify "-" as a filename.
+  `,
+  )
+
+  // flags don't take a value, they're boolean on or off, and can be
+  // turned off by prefixing with `--no-`
+  // so this adds support for -b to mean --bail, or -B to mean --no-bail
+  .flag({
+    flag: {
+      // specify a short value if you like.  this must be a single char
+      short: 'f',
+      // description is optional as well.
+      description: `Make the flags wave`,
+      // default value for flags is 'false', unless you change it
+      default: true,
+    },
+    'no-flag': {
+      // you can can always negate a flag with `--no-flag`
+      // specifying a negate option will let you define a short
+      // single-char option for negation.
+      short: 'F',
+      description: `Do not wave the flags`,
+    },
+  })
+
+  // Options that take a value are specified with `opt()`
+  .opt({
+    reporter: {
+      short: 'R',
+      description: 'the style of report to display',
+    },
+  })
+
+  // if you want a number, say so, and jackspeak will enforce it
+  .num({
+    jobs: {
+      short: 'j',
+      description: 'how many jobs to run in parallel',
+      default: 1,
+    },
+  })
+
+  // A list is an option that can be specified multiple times,
+  // to expand into an array of all the settings.  Normal opts
+  // will just give you the last value specified.
+  .optList({
+    'node-arg': {},
+  })
+
+  // a flagList is an array of booleans, so `-ddd` is [true, true, true]
+  // count the `true` values to treat it as a counter.
+  .flagList({
+    debug: { short: 'd' },
+  })
+
+  // opts take a value, and is set to the string in the results
+  // you can combine multiple short-form flags together, but
+  // an opt will end the combine chain, posix-style.  So,
+  // -bofilename would be like --bail --output-file=filename
+  .opt({
+    'output-file': {
+      short: 'o',
+      // optional: make it -o<file> in the help output insead of -o<value>
+      hint: 'file',
+      description: `Send the raw output to the specified file.`,
+    },
+  })
+
+// now we can parse argv like this:
+const { values, positionals } = j.parse(process.argv)
+
+// or decide to show the usage banner
+console.log(j.usage())
+
+// or validate an object config we got from somewhere else
+try {
+  j.validate(someConfig)
+} catch (er) {
+  console.error('someConfig is not valid!', er)
+}
+```
+
+## Name
+
+The inspiration for this module is [yargs](http://npm.im/yargs), which
+is pirate talk themed. Yargs has all the features, and is infinitely
+flexible. "Jackspeak" is the slang of the royal navy. This module
+does not have all the features. It is declarative and rigid by design.

node_modules/jest-worker/README.md

@@ -0,0 +1,272 @@
+# jest-worker
+
+Module for executing heavy tasks under forked processes in parallel, by providing a `Promise` based interface, minimum overhead, and bound workers.
+
+The module works by providing an absolute path of the module to be loaded in all forked processes. All methods are exposed on the parent process as promises, so they can be `await`'ed. Child (worker) methods can either be synchronous or asynchronous.
+
+The module also implements support for bound workers. Binding a worker means that, based on certain parameters, the same task will always be executed by the same worker. The way bound workers work is by using the returned string of the `computeWorkerKey` method. If the string was used before for a task, the call will be queued to the related worker that processed the task earlier; if not, it will be executed by the first available worker, then sticked to the worker that executed it; so the next time it will be processed by the same worker. If you have no preference on the worker executing the task, but you have defined a `computeWorkerKey` method because you want _some_ of the tasks to be sticked, you can return `null` from it.
+
+The list of exposed methods can be explicitly provided via the `exposedMethods` option. If it is not provided, it will be obtained by requiring the child module into the main process, and analyzed via reflection. Check the "minimal example" section for a valid one.
+
+## Install
+
+```sh
+yarn add jest-worker
+```
+
+## Example
+
+This example covers the minimal usage:
+
+### File `parent.js`
+
+```js
+import {Worker as JestWorker} from 'jest-worker';
+
+async function main() {
+  const worker = new JestWorker(require.resolve('./worker'));
+  const result = await worker.hello('Alice'); // "Hello, Alice"
+}
+
+main();
+```
+
+### File `worker.js`
+
+```js
+export function hello(param) {
+  return `Hello, ${param}`;
+}
+```
+
+## Experimental worker
+
+Node shipped with [`worker_threads`](https://nodejs.org/api/worker_threads.html), a "threading API" that uses `SharedArrayBuffers` to communicate between the main process and its child threads. This feature can significantly improve the communication time between parent and child processes in `jest-worker`.
+
+To use `worker_threads` instead of default `child_process` you have to pass `enableWorkerThreads: true` when instantiating the worker.
+
+## API
+
+The `Worker` export is a constructor that is initialized by passing the worker path, plus an options object.
+
+### `workerPath: string | URL` (required)
+
+Node module name or absolute path or file URL of the file to be loaded in the child processes. You can use `require.resolve` to transform a relative path into an absolute one.
+
+### `options: Object` (optional)
+
+#### `computeWorkerKey: (method: string, ...args: Array<unknown>) => string | null` (optional)
+
+Every time a method exposed via the API is called, `computeWorkerKey` is also called in order to bound the call to a worker. This is useful for workers that are able to cache the result or part of it. You bound calls to a worker by making `computeWorkerKey` return the same identifier for all different calls. If you do not want to bind the call to any worker, return `null`.
+
+The callback you provide is called with the method name, plus all the rest of the arguments of the call. Thus, you have full control to decide what to return. Check a practical example on bound workers under the "bound worker usage" section.
+
+By default, no process is bound to any worker.
+
+#### `enableWorkerThreads: boolean` (optional)
+
+By default, `jest-worker` will use `child_process` threads to spawn new Node.js processes. If you prefer [`worker_threads`](https://nodejs.org/api/worker_threads.html) instead, pass `enableWorkerThreads: true`.
+
+#### `exposedMethods: ReadonlyArray<string>` (optional)
+
+List of method names that can be called on the child processes from the parent process. You cannot expose any method named like a public `Worker` method, or starting with `_`. If you use method auto-discovery, then these methods will not be exposed, even if they exist.
+
+#### `forkOptions: ForkOptions` (optional)
+
+Allow customizing all options passed to `child_process.fork`. By default, some values are set (`cwd`, `env`, `execArgv` and `serialization`), but you can override them and customize the rest. For a list of valid values, check [the Node documentation](https://nodejs.org/api/child_process.html#child_process_child_process_fork_modulepath_args_options).
+
+#### `idleMemoryLimit: number` (optional)
+
+Specifies the memory limit for workers before they are recycled and is primarily a work-around for [this issue](https://github.com/jestjs/jest/issues/11956);
+
+After the worker has executed a task the memory usage of it is checked. If it exceeds the value specified the worker is killed and restarted. If no limit is set this process does not occur. The limit can be specified in 2 ways:
+
+- `<= 1` - The value is assumed to be a percentage of system memory. So 0.5 sets the memory limit of the worker to half of the total system memory
+- `\> 1` - Assumed to be a fixed byte value. Because of the previous rule if you wanted a value of 1 byte (I don't know why) you could use `1.1`.
+
+#### `maxRetries: number` (optional)
+
+Maximum amount of times that a dead child can be re-spawned, per call. Defaults to `3`, pass `Infinity` to allow endless retries.
+
+#### `numWorkers: number` (optional)
+
+Amount of workers to spawn. Defaults to the number of CPUs minus 1.
+
+#### `resourceLimits: ResourceLimits` (optional)
+
+The `resourceLimits` option which will be passed to `worker_threads` workers.
+
+#### `silent: Boolean` (optional)
+
+Set to false for `stdout` and `stderr` to be logged to console.
+
+By default this is true.
+
+#### `setupArgs: Array<unknown>` (optional)
+
+The arguments that will be passed to the `setup` method during initialization.
+
+#### `taskQueue: TaskQueue` (optional)
+
+The task queue defines in which order tasks (method calls) are processed by the workers. `jest-worker` ships with a `FifoQueue` and `PriorityQueue`:
+
+- `FifoQueue` (default): Processes the method calls (tasks) in the call order.
+- `PriorityQueue`: Processes the method calls by a computed priority in natural ordering (lower priorities first). Tasks with the same priority are processed in any order (FIFO not guaranteed). The constructor accepts a single argument, the function that is passed the name of the called function and the arguments and returns a numerical value for the priority: `new require('jest-worker').PriorityQueue((method, filename) => filename.length)`.
+
+#### `WorkerPool: new (workerPath: string, options?: WorkerPoolOptions) => WorkerPoolInterface` (optional)
+
+Provide a custom WorkerPool class to be used for spawning child processes.
+
+#### `workerSchedulingPolicy: 'round-robin' | 'in-order'` (optional)
+
+Specifies the policy how tasks are assigned to workers if multiple workers are _idle_:
+
+- `round-robin` (default): The task will be sequentially distributed onto the workers. The first task is assigned to the worker 1, the second to the worker 2, to ensure that the work is distributed across workers.
+- `in-order`: The task will be assigned to the first free worker starting with worker 1 and only assign the work to worker 2 if the worker 1 is busy.
+
+Tasks are always assigned to the first free worker as soon as tasks start to queue up. The scheduling policy does not define the task scheduling which is always first-in, first-out.
+
+## JestWorker
+
+### Methods
+
+The returned `JestWorker` instance has all the exposed methods, plus some additional ones to interact with the workers itself:
+
+#### `getStdout(): Readable`
+
+Returns a `ReadableStream` where the standard output of all workers is piped. Note that the `silent` option of the child workers must be set to `true` to make it work. This is the default set by `jest-worker`, but keep it in mind when overriding options through `forkOptions`.
+
+#### `getStderr(): Readable`
+
+Returns a `ReadableStream` where the standard error of all workers is piped. Note that the `silent` option of the child workers must be set to `true` to make it work. This is the default set by `jest-worker`, but keep it in mind when overriding options through `forkOptions`.
+
+#### `start()`
+
+Starts up every worker and calls their `setup` function, if it exists. Returns a `Promise` which resolves when all workers are running and have completed their `setup`.
+
+This is useful if you want to start up all your workers eagerly before they are used to call any other functions.
+
+#### `end()`
+
+Finishes the workers by killing all workers. No further calls can be done to the `Worker` instance.
+
+Returns a `Promise` that resolves with `{ forceExited: boolean }` once all workers are dead. If `forceExited` is `true`, at least one of the workers did not exit gracefully, which likely happened because it executed a leaky task that left handles open. This should be avoided, force exiting workers is a last resort to prevent creating lots of orphans.
+
+**Note:**
+
+`await`ing the `end()` Promise immediately after the workers are no longer needed before proceeding to do other useful things in your program may not be a good idea. If workers have to be force exited, `jest-worker` may go through multiple stages of force exiting (e.g. SIGTERM, later SIGKILL) and give the worker overall around 1 second time to exit on its own. During this time, your program will wait, even though it may not be necessary that all workers are dead before continuing execution.
+
+Consider deliberately leaving this Promise floating (unhandled resolution). After your program has done the rest of its work and is about to exit, the Node process will wait for the Promise to resolve after all workers are dead as the last event loop task. That way you parallelized computation time of your program and waiting time and you didn't delay the outputs of your program unnecessarily.
+
+### Worker IDs
+
+Each worker has a unique id (index that starts with `'1'`), which is available inside the worker as `process.env.JEST_WORKER_ID`.
+
+## Setting up and tearing down the child process
+
+The child process can define two special methods (both of them can be asynchronous):
+
+- `setup()`: If defined, it's executed before the first call to any method in the child.
+- `teardown()`: If defined, it's executed when the farm ends.
+
+# More examples
+
+## Standard usage
+
+This example covers the standard usage:
+
+### File `parent.js`
+
+```js
+import {Worker as JestWorker} from 'jest-worker';
+
+async function main() {
+  const myWorker = new JestWorker(require.resolve('./worker'), {
+    exposedMethods: ['foo', 'bar', 'getWorkerId'],
+    numWorkers: 4,
+  });
+
+  console.log(await myWorker.foo('Alice')); // "Hello from foo: Alice"
+  console.log(await myWorker.bar('Bob')); // "Hello from bar: Bob"
+  console.log(await myWorker.getWorkerId()); // "3" -> this message has sent from the 3rd worker
+
+  const {forceExited} = await myWorker.end();
+  if (forceExited) {
+    console.error('Workers failed to exit gracefully');
+  }
+}
+
+main();
+```
+
+### File `worker.js`
+
+```js
+export function foo(param) {
+  return `Hello from foo: ${param}`;
+}
+
+export function bar(param) {
+  return `Hello from bar: ${param}`;
+}
+
+export function getWorkerId() {
+  return process.env.JEST_WORKER_ID;
+}
+```
+
+## Bound worker usage:
+
+This example covers the usage with a `computeWorkerKey` method:
+
+### File `parent.js`
+
+```js
+import {Worker as JestWorker} from 'jest-worker';
+
+async function main() {
+  const myWorker = new JestWorker(require.resolve('./worker'), {
+    computeWorkerKey: (method, filename) => filename,
+  });
+
+  // Transform the given file, within the first available worker.
+  console.log(await myWorker.transform('/tmp/foo.js'));
+
+  // Wait a bit.
+  await sleep(10000);
+
+  // Transform the same file again. Will immediately return because the
+  // transformed file is cached in the worker, and `computeWorkerKey` ensures
+  // the same worker that processed the file the first time will process it now.
+  console.log(await myWorker.transform('/tmp/foo.js'));
+
+  const {forceExited} = await myWorker.end();
+  if (forceExited) {
+    console.error('Workers failed to exit gracefully');
+  }
+}
+
+main();
+```
+
+### File `worker.js`
+
+```js
+import babel from '@babel/core';
+
+const cache = Object.create(null);
+
+export function transform(filename) {
+  if (cache[filename]) {
+    return cache[filename];
+  }
+
+  // jest-worker can handle both immediate results and thenables. If a
+  // thenable is returned, it will be await'ed until it resolves.
+  return babel.transformFileAsync(filename).then(result => {
+    cache[filename] = result;
+
+    return result;
+  });
+}
+```