Coverage for kwai/modules/news/stories/story_query.py: 100%

1"""Module for defining a interface for a story query.""" 

2from abc import abstractmethod 

3 

4from kwai.core.domain.repository.query import Query 

5from kwai.core.domain.value_objects.unique_id import UniqueId 

6from kwai.modules.news.stories.story import StoryIdentifier 

7 

8 

9class StoryQuery(Query): 

10 """An interface for a story query.""" 

11 

12 @abstractmethod 

13 def filter_by_id(self, id_: StoryIdentifier) -> "StoryQuery": 

14 """Add a filter on the news story id. 

15 

16 Args: 

17 id_: an id of a news story. 

18 """ 

19 raise NotImplementedError 

20 

21 @abstractmethod 

22 def filter_by_publication_date( 

23 self, year: int, month: int | None = None 

24 ) -> "StoryQuery": 

25 """Add a filter on the publication date. 

26 

27 Args: 

28 year: Only return news stories published in this year. 

29 month: Only return news stories published in this month. 

30 

31 When month is omitted, all stories published in the given year will be returned. 

32 """ 

33 raise NotImplementedError 

34 

35 @abstractmethod 

36 def filter_by_promoted(self) -> "StoryQuery": 

37 """Add a filter to return only the promoted news stories.""" 

38 raise NotImplementedError 

39 

40 @abstractmethod 

41 def filter_by_application(self, application: int | str) -> "StoryQuery": 

42 """Add a filter to return only stories for the given application. 

43 

44 Args: 

45 application: The id or the name of the application 

46 """ 

47 raise NotImplementedError 

48 

49 @abstractmethod 

50 def filter_by_active(self) -> "StoryQuery": 

51 """Add a filter to only return active news stories. 

52 

53 An active story is enabled and is not expired. 

54 """ 

55 raise NotImplementedError 

56 

57 @abstractmethod 

58 def filter_by_user(self, user: int | UniqueId) -> "StoryQuery": 

59 """Add a filter to only return news stories of the given user. 

60 

61 Args: 

62 user: The id or unique id of the user. 

63 """ 

64 raise NotImplementedError 

65 

66 @abstractmethod 

67 def order_by_publication_date(self) -> "StoryQuery": 

68 """Order the result on the publication date.""" 

69 raise NotImplementedError