Skip to content

Commit 526078c

Browse files
fnesvedafnesveda
authored
Enforce use of Enum items in method arguments (#47)
Enforce use of enum items as some method arguments, add those enums to documentation, expose consts submodule
1 parent dba1522 commit 526078c

File tree

16 files changed

+343
-125
lines changed

16 files changed

+343
-125
lines changed

‎CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,11 @@ Changelog
44
[0.1.0](../../releases/tag/v0.1.0) - 2021-06-11
55
-----------------------------------------------
66

7+
### Changed
8+
9+
- methods using specific option values for arguments now use well-defined and documented `Enum`s for those arguments instead of generic strings
10+
- made the submodule `apify_client.consts` containing those `Enum`s available
11+
712
### Internal changes
813

914
- updated development dependencies

‎docs/docs.md‎

Lines changed: 180 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -580,7 +580,7 @@ Start the actor and immediately return the Run object.
580580
e.g. when the actor finished or failed.
581581
If you already have a webhook set up for the actor or task, you do not have to add it again here.
582582
Each webhook is represented by a dictionary containing these items:
583-
* `event_types`: list of `WebhookEventType` values which trigger the webhook
583+
* `event_types`: list of [`WebhookEventType`](#webhookeventtype) values which trigger the webhook
584584
* `request_url`: URL to which to send the webhook HTTP request
585585
* `payload_template` (optional): Optional template for the request payload
586586

@@ -694,7 +694,7 @@ Last run is retrieved based on the start time of the runs.
694694

695695
* **Parameters**
696696

697-
* **status** (`str`, *optional*) – Consider only runs with this status.
697+
* **status** ([`ActorJobStatus`](#actorjobstatus), *optional*) – Consider only runs with this status.
698698

699699
* **Returns**
700700

@@ -871,25 +871,26 @@ Update the actor version with specified fields.
871871
* **apply_env_vars_to_build** (`bool`, *optional*) – Whether the environment variables specified for the actor run
872872
will also be set to the actor build process.
873873

874-
* **source_type** (`str`, *optional*) – What source type is the actor version using. Can be one of
875-
SOURCE_CODE, SOURCE_FILES, GIT_REPO, TARBALL and GITHUB_GIST.
874+
* **source_type** ([`ActorSourceType`](#actorsourcetype), *optional*) – What source type is the actor version using.
876875

877-
* **source_code** (`str`, *optional*) – Source code as a single JavaScript/Node.js file, using the base Docker image specified in baseDockerImage.
878-
Required when source_type is SOURCE_CODE.
876+
* **source_code** (`str`, *optional*) – Source code as a single JavaScript/Node.js file,
877+
using the base Docker image specified in `baseDockerImage`.
878+
Required when `source_type` is [`ActorSourceType.SOURCE_CODE`](#actorsourcetype-source_code).
879879

880-
* **base_docker_image** (`str`, *optional*) – The base Docker image to use for single-file actors. Required when source_type is SOURCE_CODE.
880+
* **base_docker_image** (`str`, *optional*) – The base Docker image to use for single-file actors.
881+
Required when `source_type` is [`ActorSourceType.SOURCE_CODE`](#actorsourcetype-source_code).
881882

882883
* **source_files** (`list of dict`, *optional*) – Source code comprised of multiple files, each an item of the array.
883-
Required when source_type is SOURCE_FILES. See the API docs for the exact structure.
884+
Required when `source_type` is [`ActorSourceType.SOURCE_FILES`](#actorsourcetype-source_files). See the API docs for the exact structure.
884885

885886
* **git_repo_url** (`str`, *optional*) – The URL of a Git repository from which the source code will be cloned.
886-
Required when source_type is GIT_REPO.
887+
Required when `source_type` is [`ActorSourceType.GIT_REPO`](#actorsourcetype-git_repo).
887888

888889
* **tarball_url** (`str`, *optional*) – The URL of a tarball or a zip archive from which the source code will be downloaded.
889-
Required when source_type is TARBALL.
890+
Required when `source_type` is [`ActorSourceType.TARBALL`](#actorsourcetype-tarball).
890891

891892
* **github_gist_url** (`str`, *optional*) – The URL of a GitHub Gist from which the source will be downloaded.
892-
Required when source_type is GITHUB_GIST.
893+
Required when `source_type` is [`ActorSourceType.GITHUB_GIST`](#actorsourcetype-github_gist).
893894

894895
* **Returns**
895896

@@ -946,7 +947,7 @@ Create a new actor version.
946947

947948
* **Parameters**
948949

949-
* **version_number** (`str`) – Major and minor version of the actor (e.g. 1.0)
950+
* **version_number** (`str`) – Major and minor version of the actor (e.g. `1.0`)
950951

951952
* **build_tag** (`str`, *optional*) – Tag that is automatically set to the latest successful build of the current version.
952953

@@ -956,25 +957,26 @@ Create a new actor version.
956957
* **apply_env_vars_to_build** (`bool`, *optional*) – Whether the environment variables specified for the actor run
957958
will also be set to the actor build process.
958959

959-
* **source_type** (`str`) – What source type is the actor version using. Can be one of
960-
SOURCE_CODE, SOURCE_FILES, GIT_REPO, TARBALL and GITHUB_GIST.
960+
* **source_type** ([`ActorSourceType`](#actorsourcetype)) – What source type is the actor version using.
961961

962-
* **source_code** (`str`, *optional*) – Source code as a single JavaScript/Node.js file, using the base Docker image specified in baseDockerImage.
963-
Required when source_type is SOURCE_CODE.
962+
* **source_code** (`str`, *optional*) – Source code as a single JavaScript/Node.js file,
963+
using the base Docker image specified in `baseDockerImage`.
964+
Required when `source_type` is [`ActorSourceType.SOURCE_CODE`](#actorsourcetype-source_code).
964965

965-
* **base_docker_image** (`str`, *optional*) – The base Docker image to use for single-file actors. Required when source_type is SOURCE_CODE.
966+
* **base_docker_image** (`str`, *optional*) – The base Docker image to use for single-file actors.
967+
Required when `source_type` is [`ActorSourceType.SOURCE_CODE`](#actorsourcetype-source_code).
966968

967969
* **source_files** (`list of dict`, *optional*) – Source code comprised of multiple files, each an item of the array.
968-
Required when source_type is SOURCE_FILES. See the API docs for the exact structure.
970+
Required when `source_type` is [`ActorSourceType.SOURCE_FILES`](#actorsourcetype-source_files). See the API docs for the exact structure.
969971

970972
* **git_repo_url** (`str`, *optional*) – The URL of a Git repository from which the source code will be cloned.
971-
Required when source_type is GIT_REPO.
973+
Required when `source_type` is [`ActorSourceType.GIT_REPO`](#actorsourcetype-git_repo).
972974

973975
* **tarball_url** (`str`, *optional*) – The URL of a tarball or a zip archive from which the source code will be downloaded.
974-
Required when source_type is TARBALL.
976+
Required when `source_type` is [`ActorSourceType.TARBALL`](#actorsourcetype-tarball).
975977

976978
* **github_gist_url** (`str`, *optional*) – The URL of a GitHub Gist from which the source will be downloaded.
977-
Required when source_type is GITHUB_GIST.
979+
Required when `source_type` is [`ActorSourceType.GITHUB_GIST`](#actorsourcetype-github_gist).
978980

979981
* **Returns**
980982

@@ -1187,7 +1189,7 @@ List all actor runs (either of a single actor, or all user’s actors, depending
11871189

11881190
* **desc** (`bool`, *optional*) – Whether to sort the runs in descending order based on their start date
11891191

1190-
* **status** (`str`, *optional*) – Retrieve only runs with the provided status
1192+
* **status** ([`ActorJobStatus`](#actorjobstatus), *optional*) – Retrieve only runs with the provided status
11911193

11921194
* **Returns**
11931195

@@ -2141,8 +2143,7 @@ Update the webhook.
21412143

21422144
* **Parameters**
21432145

2144-
* **event_types** (`list`, *optional*) – List of event types that should trigger the webhook.
2145-
Present in the client constants as WebhookEventType. At least one is required.
2146+
* **event_types** ([`list of WebhookEventType`](#webhookeventtype), *optional*) – List of event types that should trigger the webhook. At least one is required.
21462147

21472148
* **request_url** (`str`, *optional*) – URL that will be invoked once the webhook is triggered.
21482149

@@ -2243,8 +2244,7 @@ You have to specify exactly one out of actor_id, actor_task_id or actor_run_id.
22432244

22442245
* **Parameters**
22452246

2246-
* **event_types** (`list`) – List of event types that should trigger the webhook.
2247-
Present in the client constants as WebhookEventType. At least one is required.
2247+
* **event_types** ([`list of WebhookEventType`](#webhookeventtype)) – List of event types that should trigger the webhook. At least one is required.
22482248

22492249
* **request_url** (`str`) – URL that will be invoked once the webhook is triggered.
22502250

@@ -2434,7 +2434,7 @@ Start the task and immediately return the Run object.
24342434
e.g. when the actor finished or failed.
24352435
If you already have a webhook set up for the actor or task, you do not have to add it again here.
24362436
Each webhook is represented by a dictionary containing these items:
2437-
* `event_types`: list of `WebhookEventType` values which trigger the webhook
2437+
* `event_types`: list of [`WebhookEventType`](#webhookeventtype) values which trigger the webhook
24382438
* `request_url`: URL to which to send the webhook HTTP request
24392439
* `payload_template` (optional): Optional template for the request payload
24402440

@@ -2534,7 +2534,7 @@ Last run is retrieved based on the start time of the runs.
25342534

25352535
* **Parameters**
25362536

2537-
* **status** (`str`, *optional*) – Consider only runs with this status.
2537+
* **status** ([`ActorJobStatus`](#actorjobstatus), *optional*) – Consider only runs with this status.
25382538

25392539
* **Returns**
25402540

@@ -2815,3 +2815,155 @@ Name | Type | Description
28152815
`total` | `int` | Total number of objects matching the API call criteria
28162816

28172817
***
2818+
2819+
### [](#actorjobstatus) ActorJobStatus
2820+
2821+
Available statuses for actor jobs (runs or builds).
2822+
2823+
* [READY](#actorjobstatus-ready)
2824+
* [RUNNING](#actorjobstatus-running)
2825+
* [SUCCEEDED](#actorjobstatus-succeeded)
2826+
* [FAILED](#actorjobstatus-failed)
2827+
* [TIMING\_OUT](#actorjobstatus-timing\_out)
2828+
* [TIMED\_OUT](#actorjobstatus-timed\_out)
2829+
* [ABORTING](#actorjobstatus-aborting)
2830+
* [ABORTED](#actorjobstatus-aborted)
2831+
2832+
***
2833+
2834+
#### [](#actorjobstatus-ready) `ActorJobStatus.READY`
2835+
2836+
Actor job initialized but not started yet
2837+
2838+
***
2839+
2840+
#### [](#actorjobstatus-running) `ActorJobStatus.RUNNING`
2841+
2842+
Actor job in progress
2843+
2844+
***
2845+
2846+
#### [](#actorjobstatus-succeeded) `ActorJobStatus.SUCCEEDED`
2847+
2848+
Actor job finished successfully
2849+
2850+
***
2851+
2852+
#### [](#actorjobstatus-failed) `ActorJobStatus.FAILED`
2853+
2854+
Actor job or build failed
2855+
2856+
***
2857+
2858+
#### [](#actorjobstatus-timing_out) `ActorJobStatus.TIMING_OUT`
2859+
2860+
Actor job currently timing out
2861+
2862+
***
2863+
2864+
#### [](#actorjobstatus-timed_out) `ActorJobStatus.TIMED_OUT`
2865+
2866+
Actor job timed out
2867+
2868+
***
2869+
2870+
#### [](#actorjobstatus-aborting) `ActorJobStatus.ABORTING`
2871+
2872+
Actor job currently being aborted by user
2873+
2874+
***
2875+
2876+
#### [](#actorjobstatus-aborted) `ActorJobStatus.ABORTED`
2877+
2878+
Actor job aborted by user
2879+
2880+
***
2881+
2882+
### [](#actorsourcetype) ActorSourceType
2883+
2884+
Available source types for actors.
2885+
2886+
* [SOURCE\_CODE](#actorsourcetype-source\_code)
2887+
* [SOURCE\_FILES](#actorsourcetype-source\_files)
2888+
* [GIT\_REPO](#actorsourcetype-git\_repo)
2889+
* [TARBALL](#actorsourcetype-tarball)
2890+
* [GITHUB\_GIST](#actorsourcetype-github\_gist)
2891+
2892+
***
2893+
2894+
#### [](#actorsourcetype-source_code) `ActorSourceType.SOURCE_CODE`
2895+
2896+
Actor source code is a single JavaScript/Node.js file
2897+
2898+
***
2899+
2900+
#### [](#actorsourcetype-source_files) `ActorSourceType.SOURCE_FILES`
2901+
2902+
Actor source code is comprised of multiple files
2903+
2904+
***
2905+
2906+
#### [](#actorsourcetype-git_repo) `ActorSourceType.GIT_REPO`
2907+
2908+
Actor source code is cloned from a Git repository
2909+
2910+
***
2911+
2912+
#### [](#actorsourcetype-tarball) `ActorSourceType.TARBALL`
2913+
2914+
Actor source code is downloaded using a tarball or Zip file
2915+
2916+
***
2917+
2918+
#### [](#actorsourcetype-github_gist) `ActorSourceType.GITHUB_GIST`
2919+
2920+
Actor source code is taken from a GitHub Gist
2921+
2922+
***
2923+
2924+
### [](#webhookeventtype) WebhookEventType
2925+
2926+
Events that can trigger a webhook.
2927+
2928+
* [ACTOR\_RUN\_CREATED](#webhookeventtype-actor\_run\_created)
2929+
* [ACTOR\_RUN\_SUCCEEDED](#webhookeventtype-actor\_run\_succeeded)
2930+
* [ACTOR\_RUN\_FAILED](#webhookeventtype-actor\_run\_failed)
2931+
* [ACTOR\_RUN\_TIMED\_OUT](#webhookeventtype-actor\_run\_timed\_out)
2932+
* [ACTOR\_RUN\_ABORTED](#webhookeventtype-actor\_run\_aborted)
2933+
* [ACTOR\_RUN\_RESURRECTED](#webhookeventtype-actor\_run\_resurrected)
2934+
2935+
***
2936+
2937+
#### [](#webhookeventtype-actor_run_created) `WebhookEventType.ACTOR_RUN_CREATED`
2938+
2939+
The actor run was created
2940+
2941+
***
2942+
2943+
#### [](#webhookeventtype-actor_run_succeeded) `WebhookEventType.ACTOR_RUN_SUCCEEDED`
2944+
2945+
The actor run has succeeded
2946+
2947+
***
2948+
2949+
#### [](#webhookeventtype-actor_run_failed) `WebhookEventType.ACTOR_RUN_FAILED`
2950+
2951+
The actor run has failed
2952+
2953+
***
2954+
2955+
#### [](#webhookeventtype-actor_run_timed_out) `WebhookEventType.ACTOR_RUN_TIMED_OUT`
2956+
2957+
The actor run has timed out
2958+
2959+
***
2960+
2961+
#### [](#webhookeventtype-actor_run_aborted) `WebhookEventType.ACTOR_RUN_ABORTED`
2962+
2963+
The actor run was aborted
2964+
2965+
***
2966+
2967+
#### [](#webhookeventtype-actor_run_resurrected) `WebhookEventType.ACTOR_RUN_RESURRECTED`
2968+
2969+
The actor run was resurrected

0 commit comments

Comments
 (0)