35
35
36
36
from .utils import LOGGER , first_line , req_missing
37
37
38
+ try :
39
+ from typing import *
40
+ if TYPE_CHECKING :
41
+ import nikola # NOQA
42
+ import nikola .post # NOQA
43
+ except ImportError :
44
+ pass
45
+
38
46
__all__ = (
39
47
'Command' ,
40
48
'LateTask' ,
@@ -90,11 +98,11 @@ def get_deps(self, filename):
90
98
class PostScanner (BasePlugin ):
91
99
"""The scan method of these plugins is called by Nikola.scan_posts."""
92
100
93
- def scan (self ):
101
+ def scan (self ) -> 'List[nikola.post.Post]' :
94
102
"""Create a list of posts from some source. Returns a list of Post objects."""
95
103
raise NotImplementedError ()
96
104
97
- def supported_extensions (self ):
105
+ def supported_extensions (self ) -> 'Optional[List]' :
98
106
"""Return a list of supported file extensions, or None if such a list isn't known beforehand."""
99
107
return None
100
108
@@ -122,7 +130,7 @@ def __call__(self, config=None, **kwargs):
122
130
DoitCommand .__init__ (self , config , ** kwargs )
123
131
return self
124
132
125
- def execute (self , options = None , args = None ):
133
+ def execute (self , options = None , args = None ) -> int :
126
134
"""Check if the command can run in the current environment, fail if needed, or call _execute."""
127
135
options = options or {}
128
136
args = args or []
@@ -132,7 +140,7 @@ def execute(self, options=None, args=None):
132
140
return False
133
141
return self ._execute (options , args )
134
142
135
- def _execute (self , options , args ):
143
+ def _execute (self , options , args ) -> int :
136
144
"""Do whatever this command does.
137
145
138
146
@param options (dict) with values from cmd_options
@@ -171,11 +179,11 @@ class BaseTask(BasePlugin):
171
179
# the others have to be specifie in the command line.
172
180
is_default = True
173
181
174
- def gen_tasks (self ):
182
+ def gen_tasks (self ) -> 'List[dict]' :
175
183
"""Generate tasks."""
176
184
raise NotImplementedError ()
177
185
178
- def group_task (self ):
186
+ def group_task (self ) -> dict :
179
187
"""Return dict for group task."""
180
188
return {
181
189
'basename' : self .name ,
@@ -201,39 +209,39 @@ class TemplateSystem(BasePlugin):
201
209
202
210
name = "dummy_templates"
203
211
204
- def set_directories (self , directories , cache_folder ):
212
+ def set_directories (self , directories : 'List[str]' , cache_folder : str ):
205
213
"""Set the list of folders where templates are located and cache."""
206
214
raise NotImplementedError ()
207
215
208
- def template_deps (self , template_name ):
216
+ def template_deps (self , template_name : str ):
209
217
"""Return filenames which are dependencies for a template."""
210
218
raise NotImplementedError ()
211
219
212
- def get_deps (self , filename ):
220
+ def get_deps (self , filename : str ):
213
221
"""Return paths to dependencies for the template loaded from filename."""
214
222
raise NotImplementedError ()
215
223
216
- def get_string_deps (self , text ):
224
+ def get_string_deps (self , text : str ):
217
225
"""Find dependencies for a template string."""
218
226
raise NotImplementedError ()
219
227
220
- def render_template (self , template_name , output_name , context ):
228
+ def render_template (self , template_name : str , output_name : str , context : 'Dict[str, str]' ):
221
229
"""Render template to a file using context.
222
230
223
231
This must save the data to output_name *and* return it
224
232
so that the caller may do additional processing.
225
233
"""
226
234
raise NotImplementedError ()
227
235
228
- def render_template_to_string (self , template , context ) :
236
+ def render_template_to_string (self , template : str , context : 'Dict[str, str]' ) -> str :
229
237
"""Render template to a string using context."""
230
238
raise NotImplementedError ()
231
239
232
- def inject_directory (self , directory ):
240
+ def inject_directory (self , directory : str ):
233
241
"""Inject the directory with the lowest priority in the template search mechanism."""
234
242
raise NotImplementedError ()
235
243
236
- def get_template_path (self , template_name ) :
244
+ def get_template_path (self , template_name : str ) -> str :
237
245
"""Get the path to a template or return None."""
238
246
raise NotImplementedError ()
239
247
@@ -243,7 +251,7 @@ class TaskMultiplier(BasePlugin):
243
251
244
252
name = "dummy multiplier"
245
253
246
- def process (self , task ):
254
+ def process (self , task ) -> list :
247
255
"""Examine task and create more tasks. Returns extra tasks only."""
248
256
return []
249
257
@@ -270,11 +278,11 @@ class PageCompiler(BasePlugin):
270
278
}
271
279
config_dependencies = []
272
280
273
- def get_dep_filename (self , post , lang ) :
281
+ def get_dep_filename (self , post : 'nikola.post.Post' , lang : str ) -> str :
274
282
"""Return the .dep file's name for the given post and language."""
275
283
return post .translated_base_path (lang ) + '.dep'
276
284
277
- def _read_extra_deps (self , post , lang ) :
285
+ def _read_extra_deps (self , post : 'nikola.post.Post' , lang : str ) -> 'List[str]' :
278
286
"""Read contents of .dep file and return them as a list."""
279
287
dep_path = self .get_dep_filename (post , lang )
280
288
if os .path .isfile (dep_path ):
@@ -283,9 +291,9 @@ def _read_extra_deps(self, post, lang):
283
291
return deps
284
292
return []
285
293
286
- def register_extra_dependencies (self , post ):
294
+ def register_extra_dependencies (self , post : 'nikola.post.Post' ):
287
295
"""Add dependency to post object to check .dep file."""
288
- def create_lambda (lang ) :
296
+ def create_lambda (lang : str ) -> 'Callable' :
289
297
# We create a lambda like this so we can pass `lang` to it, because if we didn’t
290
298
# add that function, `lang` would always be the last language in TRANSLATIONS.
291
299
# (See http://docs.python-guide.org/en/latest/writing/gotchas/#late-binding-closures)
@@ -294,38 +302,38 @@ def create_lambda(lang):
294
302
for lang in self .site .config ['TRANSLATIONS' ]:
295
303
post .add_dependency (create_lambda (lang ), 'fragment' , lang = lang )
296
304
297
- def get_extra_targets (self , post , lang , dest ) :
305
+ def get_extra_targets (self , post : 'nikola.post.Post' , lang : str , dest : str ) -> 'List[str]' :
298
306
"""Return a list of extra targets for the render_posts task when compiling the post for the specified language."""
299
307
if self .use_dep_file :
300
308
return [self .get_dep_filename (post , lang )]
301
309
else :
302
310
return []
303
311
304
- def compile (self , source , dest , is_two_file = True , post = None , lang = None ):
312
+ def compile (self , source : str , dest : str , is_two_file = True , post = None , lang = None ):
305
313
"""Compile the source file into HTML and save as dest."""
306
314
raise NotImplementedError ()
307
315
308
- def compile_string (self , data , source_path = None , is_two_file = True , post = None , lang = None ):
316
+ def compile_string (self , data : str , source_path = None , is_two_file = True , post = None , lang = None ) -> str :
309
317
"""Compile the source file into HTML strings (with shortcode support).
310
318
311
319
Returns a tuple of at least two elements: HTML string [0] and shortcode dependencies [last].
312
320
"""
313
321
# This function used to have some different APIs in different places.
314
322
raise NotImplementedError ()
315
323
316
- def create_post (self , path , content = None , onefile = False , is_page = False , ** kw ):
324
+ def create_post (self , path : str , content = None , onefile = False , is_page = False , ** kw ):
317
325
"""Create post file with optional metadata."""
318
326
raise NotImplementedError ()
319
327
320
- def extension (self ):
328
+ def extension (self ) -> str :
321
329
"""Return the preferred extension for the output of this compiler."""
322
330
return ".html"
323
331
324
- def read_metadata (self , post , lang = None ):
332
+ def read_metadata (self , post : 'nikola.post.Post' , lang = None ) -> 'Dict[str, str]' :
325
333
"""Read the metadata from a post, and return a metadata dict."""
326
334
return {}
327
335
328
- def split_metadata (self , data , post = None , lang = None ):
336
+ def split_metadata (self , data : str , post = None , lang = None ) -> ( str , str ):
329
337
"""Split data from metadata in the raw post content."""
330
338
if lang and post :
331
339
extractor = post .used_extractor [lang ]
@@ -338,7 +346,7 @@ def split_metadata(self, data, post=None, lang=None):
338
346
else :
339
347
return data , data
340
348
341
- def get_compiler_extensions (self ):
349
+ def get_compiler_extensions (self ) -> list :
342
350
"""Activate all the compiler extension plugins for a given compiler and return them."""
343
351
plugins = []
344
352
for plugin_info in self .site .compiler_extensions :
@@ -399,7 +407,7 @@ class MetadataExtractor(BasePlugin):
399
407
# Whether or not the extractor supports writing metadata.
400
408
supports_write = False
401
409
402
- def _extract_metadata_from_text (self , source_text : str ) -> dict :
410
+ def _extract_metadata_from_text (self , source_text : str ) -> 'Dict[str, str]' :
403
411
"""Extract metadata from text."""
404
412
raise NotImplementedError ()
405
413
@@ -415,17 +423,17 @@ def split_metadata_from_text(self, source_text: str) -> (str, str):
415
423
# Necessary?
416
424
return split_result [0 ], split_result [- 1 ]
417
425
418
- def extract_text (self , source_text : str ) -> dict :
426
+ def extract_text (self , source_text : str ) -> 'Dict[str, str]' :
419
427
"""Split file, return metadata and the content."""
420
428
split = self .split_metadata_from_text (source_text )
421
429
meta = self ._extract_metadata_from_text (split [0 ])
422
430
return meta
423
431
424
- def extract_filename (self , filename : str , lang : str ) -> dict :
432
+ def extract_filename (self , filename : str , lang : str ) -> 'Dict[str, str]' :
425
433
"""Extract metadata from filename."""
426
434
return {}
427
435
428
- def write_metadata (self , metadata : dict , comment_wrap = False ) -> str :
436
+ def write_metadata (self , metadata : 'Dict[str, str]' , comment_wrap = False ) -> str :
429
437
"""Write metadata in this extractor’s format.
430
438
431
439
``comment_wrap`` is either True, False, or a 2-tuple of comments to use for wrapping, if necessary.
@@ -499,7 +507,7 @@ def _execute(self, options={}, args=[]):
499
507
"""Import the data into Nikola."""
500
508
raise NotImplementedError ()
501
509
502
- def generate_base_site (self , path ):
510
+ def generate_base_site (self , path : str ):
503
511
"""Create the base site."""
504
512
raise NotImplementedError ()
505
513
@@ -700,7 +708,7 @@ class Taxonomy(BasePlugin):
700
708
'taxonomy_rss' : '' ,
701
709
}
702
710
703
- def is_enabled (self , lang = None ):
711
+ def is_enabled (self , lang = None ) -> bool :
704
712
"""Return True if this taxonomy is enabled, or False otherwise.
705
713
706
714
If lang is None, this determins whether the classification is
@@ -710,18 +718,18 @@ def is_enabled(self, lang=None):
710
718
"""
711
719
return True
712
720
713
- def get_implicit_classifications (self , lang ) :
721
+ def get_implicit_classifications (self , lang : str ) -> 'List[str]' :
714
722
"""Return a list of classification strings which should always appear in posts_per_classification."""
715
723
return []
716
724
717
- def classify (self , post , lang ) :
725
+ def classify (self , post : 'nikola.post.Post' , lang : str ) -> 'Iterable[str]' :
718
726
"""Classify the given post for the given language.
719
727
720
728
Must return a list or tuple of strings.
721
729
"""
722
730
raise NotImplementedError ()
723
731
724
- def sort_posts (self , posts , classification , lang ):
732
+ def sort_posts (self , posts : 'List[nikola.post.Post]' , classification : str , lang : str ):
725
733
"""Sort the given list of posts.
726
734
727
735
Allows the plugin to order the posts per classification as it wants.
@@ -730,7 +738,7 @@ def sort_posts(self, posts, classification, lang):
730
738
"""
731
739
pass
732
740
733
- def sort_classifications (self , classifications , lang , level = None ):
741
+ def sort_classifications (self , classifications : 'List[str]' , lang : str , level = None ):
734
742
"""Sort the given list of classification strings.
735
743
736
744
Allows the plugin to order the classifications as it wants. The
@@ -743,7 +751,7 @@ def sort_classifications(self, classifications, lang, level=None):
743
751
"""
744
752
pass
745
753
746
- def get_classification_friendly_name (self , classification , lang , only_last_component = False ):
754
+ def get_classification_friendly_name (self , classification : str , lang : str , only_last_component = False ) -> str :
747
755
"""Extract a friendly name from the classification.
748
756
749
757
The result of this function is usually displayed to the user, instead
@@ -755,7 +763,7 @@ def get_classification_friendly_name(self, classification, lang, only_last_compo
755
763
"""
756
764
raise NotImplementedError ()
757
765
758
- def get_overview_path (self , lang , dest_type = 'page' ):
766
+ def get_overview_path (self , lang : str , dest_type = 'page' ) -> str :
759
767
"""Return path for classification overview.
760
768
761
769
This path handler for the classification overview must return one or
@@ -776,7 +784,7 @@ def get_overview_path(self, lang, dest_type='page'):
776
784
"""
777
785
raise NotImplementedError ()
778
786
779
- def get_path (self , classification , lang , dest_type = 'page' ):
787
+ def get_path (self , classification : str , lang : str , dest_type = 'page' ) -> str :
780
788
"""Return path to the classification page.
781
789
782
790
This path handler for the given classification must return one to
@@ -804,23 +812,23 @@ def get_path(self, classification, lang, dest_type='page'):
804
812
"""
805
813
raise NotImplementedError ()
806
814
807
- def extract_hierarchy (self , classification ) :
815
+ def extract_hierarchy (self , classification : str ) -> 'List[str]' :
808
816
"""Given a classification, return a list of parts in the hierarchy.
809
817
810
818
For non-hierarchical taxonomies, it usually suffices to return
811
819
`[classification]`.
812
820
"""
813
821
return [classification ]
814
822
815
- def recombine_classification_from_hierarchy (self , hierarchy ) :
823
+ def recombine_classification_from_hierarchy (self , hierarchy : 'List[str]' ) -> str :
816
824
"""Given a list of parts in the hierarchy, return the classification string.
817
825
818
826
For non-hierarchical taxonomies, it usually suffices to return hierarchy[0].
819
827
"""
820
828
return hierarchy [0 ]
821
829
822
- def provide_overview_context_and_uptodate (self , lang ) :
823
- """Provide data for the context and the uptodate list for the classifiation overview.
830
+ def provide_overview_context_and_uptodate (self , lang : str ) -> str :
831
+ """Provide data for the context and the uptodate list for the classification overview.
824
832
825
833
Must return a tuple of two dicts. The first is merged into the page's context,
826
834
the second will be put into the uptodate list of all generated tasks.
@@ -829,8 +837,8 @@ def provide_overview_context_and_uptodate(self, lang):
829
837
"""
830
838
raise NotImplementedError ()
831
839
832
- def provide_context_and_uptodate (self , classification , lang , node = None ):
833
- """Provide data for the context and the uptodate list for the list of the given classifiation .
840
+ def provide_context_and_uptodate (self , classification : str , lang : str , node = None ) -> 'Tuple[Dict]' :
841
+ """Provide data for the context and the uptodate list for the list of the given classification .
834
842
835
843
Must return a tuple of two dicts. The first is merged into the page's context,
836
844
the second will be put into the uptodate list of all generated tasks.
@@ -842,15 +850,15 @@ def provide_context_and_uptodate(self, classification, lang, node=None):
842
850
"""
843
851
raise NotImplementedError ()
844
852
845
- def should_generate_classification_page (self , classification , post_list , lang ) :
853
+ def should_generate_classification_page (self , classification : str , post_list : 'List[nikola.post.Post]' , lang : str ) -> bool :
846
854
"""Only generates list of posts for classification if this function returns True."""
847
855
return True
848
856
849
- def should_generate_rss_for_classification_page (self , classification , post_list , lang ) :
857
+ def should_generate_rss_for_classification_page (self , classification : str , post_list : 'List[nikola.post.Post]' , lang : str ) -> bool :
850
858
"""Only generates RSS feed for list of posts for classification if this function returns True."""
851
859
return self .should_generate_classification_page (classification , post_list , lang )
852
860
853
- def postprocess_posts_per_classification (self , posts_per_classification_per_language , flat_hierarchy_per_lang = None , hierarchy_lookup_per_lang = None ):
861
+ def postprocess_posts_per_classification (self , posts_per_classification_per_language : 'List[nikola.post.Post]' , flat_hierarchy_per_lang = None , hierarchy_lookup_per_lang = None ) -> 'List[nikola.post.Post]' :
854
862
"""Rearrange, modify or otherwise use the list of posts per classification and per language.
855
863
856
864
For compatibility reasons, the list could be stored somewhere else as well.
@@ -862,7 +870,7 @@ def postprocess_posts_per_classification(self, posts_per_classification_per_lang
862
870
"""
863
871
pass
864
872
865
- def get_other_language_variants (self , classification , lang , classifications_per_language ) :
873
+ def get_other_language_variants (self , classification : str , lang : str , classifications_per_language : 'List[str]' ) -> 'List[str]' :
866
874
"""Return a list of variants of the same classification in other languages.
867
875
868
876
Given a `classification` in a language `lang`, return a list of pairs
0 commit comments