Coverage for api/serializers/docs.py: 100%

1from django.conf import settings 

2 

3from api.constants.parameters import COLLECTION, TAG 

4 

5 

6UNSTABLE_WARNING = """ 

7\n\n_Caution: Parameters prefixed with `unstable__` are experimental and 

8may change or be removed without notice in future updates. Use them 

9with caution as they are not covered by our API versioning policy._\n\n 

10""" 

11 

12 

13CREATOR_COLLECTIONS_DISABLED = """ 

14Search by creator only. Cannot be used with `q`. The search 

15is fuzzy, so `creator=john` will match any value that includes the 

16word `john`. If the value contains space, items that contain any of 

17the words in the value will match. To search for several values, 

18join them with a comma.""" 

19 

20CREATOR = f""" 

21_When `q` parameter is present, `creator` parameter is ignored._ 

22 

23**Creator collection** 

24When used with `{COLLECTION}=creator&source=sourceName`, returns the collection of media 

25by the specified creator. Notice that a single creator's media items 

26can be found on several sources, but this collection only returns the 

27items from the specified source. 

28This is why for this collection, both the creator and the source 

29parameters are required, and matched exactly. For a fuzzy creator search, 

30use the default search without the `{COLLECTION}` parameter. 

31 

32**Creator search** 

33When used without the `{COLLECTION}` parameter, will search in the creator field only. 

34The search is fuzzy, so `creator=john` will match any value that includes the 

35word `john`. If the value contains space, items that contain any of 

36the words in the value will match. To search for several values, 

37join them with a comma. 

38""" 

39 

40CREATOR_HELP_TEXT = ( 

41 CREATOR if settings.SHOW_COLLECTION_DOCS else CREATOR_COLLECTIONS_DISABLED 

42) 

43COLLECTION_HELP_TEXT = f""" 

44{UNSTABLE_WARNING} 

45The kind of media collection to return. 

46 

47Must be used with `{TAG}`, `source` or `creator`+`source`""" 

48 

49EXCLUDED_SOURCE_HELP_TEXT = """ 

50A comma separated list of data sources to exclude from the search. 

51Valid values are `source_name`s from the stats endpoint: {origin}/v1/{media_path}/stats/. 

52""" 

53SOURCE_HELP_TEXT_COLLECTIONS_DISABLED = """ 

54A comma separated list of data sources; valid values are 

55`source_name`s from the stats endpoint: {origin}/v1/{media_path}/stats/.""" 

56 

57SOURCE = """ 

58For default search, a comma separated list of data sources. 

59When the `{collection_param}` parameter is used, this parameter only accepts a single source. 

60 

61Valid values are `source_name`s from the stats endpoint: {origin}/v1/{media_path}/stats/. 

62""" 

63 

64SOURCE_HELP_TEXT = ( 

65 SOURCE if settings.SHOW_COLLECTION_DOCS else SOURCE_HELP_TEXT_COLLECTIONS_DISABLED 

66) 

67 

68TAG_HELP_TEXT = f""" 

69{UNSTABLE_WARNING} 

70_Must be used with `{COLLECTION}=tag`_ 

71 

72Get the collection of media with a specific tag. Returns the collection of media 

73that has the specified tag, matching exactly and entirely. 

74 

75Differences that will cause tags to not match are: 

76- upper and lower case letters 

77- diacritical marks 

78- hyphenation 

79- spacing 

80- multi-word tags where the query is only one of the words in the tag 

81- multi-word tags where the words are in a different order. 

82 

83Examples of tags that **do not** match: 

84- "Low-Quality" and "low-quality" 

85- "jalapeño" and "jalapeno" 

86- "Saint Pierre des Champs" and "Saint-Pierre-des-Champs" 

87- "dog walking" and "dog walking" (where the latter has two spaces between the 

88last two words, as in a typographical error) 

89- "runner" and "marathon runner" 

90- "exclaiming loudly" and "loudly exclaiming" 

91 

92For non-exact or multi-tag matching, using the `tags` query parameter. 

93"""