Repository: getpelican/pelican

Issue:
Support string formatted dates for DEFAULT_DATE
Currently the documentation implies that it supports various formats, but does not explain which. The most intuitive one however is not supported.

It would make sense that this option would support the format of the meta tag that it seeks to provide a default value for, as this would be the most intuitive value type.

Support string formatted dates for DEFAULT_DATE
Currently the documentation implies that it supports various formats, but does not explain which. The most intuitive one however is not supported.

It would make sense that this option would support the format of the meta tag that it seeks to provide a default value for, as this would be the most intuitive value type.



Discussion:
I'm not sure what you mean by "string formatted dates", but there is `DEFAULT_DATE_FORMAT` and `DATE_FORMATS` to control the output format of dates. `DEFAULT_DATE` is supposed to fill in the `date` field for articles that doesn't specify it.

I mean I should be able to define it as:

```
DEFAULT_DATE = "2014-09-16"
```

Currently this does not work.

Well, you can do:

```
DEFAULT_DATE = (2014, 9, 16)
```

I know, I've gotten around the problem already, I'm giving a suggestion on how to improve Pelican and make it more intuitive for newcomers. Your suggestion, while valid, is not intuitive.

I don't think it's a question about whether it's intuitive — it's a question of documentation clarity. I've assigned this issue to myself and will add an example to the Docs > Settings > DEFAULT_DATE entry in order to make this clearer.

Personally I disagree, yes the documentation should cover it but there is no reason the software cannot facilitate the most intuitive value for this variable. Especially considering it is meant to cover a meta field which holds the value as a string format.

Not everyone reads the manual. Personally I don't read the manual unless I got stuck somewhere. Good software should not "need" a manual (not saying you shouldn't have a manual, I'm saying you shouldn't "need" it).

If you would like to propose, and subsequently implement, a solution that you feel would be superior to the current method, you are of course completely welcome to do so. As it says in our documentation, improvements are encouraged — that is what open source is all about.  (^_^)

Regarding documentation, I do not agree with your stance on that topic. We try to make Pelican as easy to use as we can, and indeed it is — in my opinion — relatively easy to get started. But saying that you shouldn't need to read the documentation in order to _configure_ Pelican, with all of the switches and knobs that provide its flexibility, is simply madness.

I'll leave the documentation topic alone as that's a whole different conversation.

Of course it's up to you how you take my suggestion. I will say though that my suggestion is not meant to be "superior", it's simply meant to make things easier for newcomers. I don't see any technical reason why you wouldnt want to support string formatted dates. I personally do not really care for my own use whether they are supported or not because I by now know what format to use. My only point in creating this ticket was to communicate to you "hey, I'm new, and I got stuck on this. You could avoid other users getting stuck on the same thing by adding support for string formatted dates".

Principle of least surprise would lead me to anticipate that `DEFAULT_DATE` accepts the same format as an article's `date` metadata field.

The simplest change I can imagine is to take this in `readers.py`:

```
metadata['date'] = SafeDatetime(*settings['DEFAULT_DATE'])
```

And instead call `get_date` from `utils` if we have a string:

```
if isinstance(settings['DEFAULT_DATE'], basestring):
    metadata['date'] = get_date(settings['DEFAULT_DATE'])
else:
    metadata['date'] = SafeDatetime(*settings['DEFAULT_DATE'])
```

This would preserve the current handling of a tuple argument, while also accepting any string that's currently acceptable for article dates.

I'm new to Python development, so it's possible that's a silly suggestion. If no one objects, I'll see if I can get as far as setting up tests and docs for that?

@Naatan: Good point, and well taken. Thanks for the feedback. Certainly didn't mean to discourage that!

@areyoutoo: Sounds fine to me. Anyone else have any thoughts on this proposal?

I'm not sure what you mean by "string formatted dates", but there is `DEFAULT_DATE_FORMAT` and `DATE_FORMATS` to control the output format of dates. `DEFAULT_DATE` is supposed to fill in the `date` field for articles that doesn't specify it.

I mean I should be able to define it as:

```
DEFAULT_DATE = "2014-09-16"
```

Currently this does not work.

Well, you can do:

```
DEFAULT_DATE = (2014, 9, 16)
```

I know, I've gotten around the problem already, I'm giving a suggestion on how to improve Pelican and make it more intuitive for newcomers. Your suggestion, while valid, is not intuitive.

I don't think it's a question about whether it's intuitive — it's a question of documentation clarity. I've assigned this issue to myself and will add an example to the Docs > Settings > DEFAULT_DATE entry in order to make this clearer.

Personally I disagree, yes the documentation should cover it but there is no reason the software cannot facilitate the most intuitive value for this variable. Especially considering it is meant to cover a meta field which holds the value as a string format.

Not everyone reads the manual. Personally I don't read the manual unless I got stuck somewhere. Good software should not "need" a manual (not saying you shouldn't have a manual, I'm saying you shouldn't "need" it).

If you would like to propose, and subsequently implement, a solution that you feel would be superior to the current method, you are of course completely welcome to do so. As it says in our documentation, improvements are encouraged — that is what open source is all about.  (^_^)

Regarding documentation, I do not agree with your stance on that topic. We try to make Pelican as easy to use as we can, and indeed it is — in my opinion — relatively easy to get started. But saying that you shouldn't need to read the documentation in order to _configure_ Pelican, with all of the switches and knobs that provide its flexibility, is simply madness.

I'll leave the documentation topic alone as that's a whole different conversation.

Of course it's up to you how you take my suggestion. I will say though that my suggestion is not meant to be "superior", it's simply meant to make things easier for newcomers. I don't see any technical reason why you wouldnt want to support string formatted dates. I personally do not really care for my own use whether they are supported or not because I by now know what format to use. My only point in creating this ticket was to communicate to you "hey, I'm new, and I got stuck on this. You could avoid other users getting stuck on the same thing by adding support for string formatted dates".

Principle of least surprise would lead me to anticipate that `DEFAULT_DATE` accepts the same format as an article's `date` metadata field.

The simplest change I can imagine is to take this in `readers.py`:

```
metadata['date'] = SafeDatetime(*settings['DEFAULT_DATE'])
```

And instead call `get_date` from `utils` if we have a string:

```
if isinstance(settings['DEFAULT_DATE'], basestring):
    metadata['date'] = get_date(settings['DEFAULT_DATE'])
else:
    metadata['date'] = SafeDatetime(*settings['DEFAULT_DATE'])
```

This would preserve the current handling of a tuple argument, while also accepting any string that's currently acceptable for article dates.

I'm new to Python development, so it's possible that's a silly suggestion. If no one objects, I'll see if I can get as far as setting up tests and docs for that?

@Naatan: Good point, and well taken. Thanks for the feedback. Certainly didn't mean to discourage that!

@areyoutoo: Sounds fine to me. Anyone else have any thoughts on this proposal?


Resolving patch:
diff --git a/pelican/readers.py b/pelican/readers.py
--- a/pelican/readers.py
+++ b/pelican/readers.py
@@ -607,7 +607,10 @@ def default_metadata(settings=None, process=None):
             metadata['category'] = value
         if settings.get('DEFAULT_DATE', None) and \
            settings['DEFAULT_DATE'] != 'fs':
-            metadata['date'] = SafeDatetime(*settings['DEFAULT_DATE'])
+            if isinstance(settings['DEFAULT_DATE'], six.string_types):
+                metadata['date'] = get_date(settings['DEFAULT_DATE'])
+            else:
+                metadata['date'] = SafeDatetime(*settings['DEFAULT_DATE'])
     return metadata
 
 


Test patch:
diff --git a/pelican/tests/test_readers.py b/pelican/tests/test_readers.py
--- a/pelican/tests/test_readers.py
+++ b/pelican/tests/test_readers.py
@@ -359,6 +359,15 @@ def test_article_with_multiple_authors_list(self):
 
         self.assertDictHasSubset(page.metadata, expected)
 
+    def test_default_date_formats(self):
+        tuple_date = self.read_file(path='article.rst',
+                                    DEFAULT_DATE=(2012, 5, 1))
+        string_date = self.read_file(path='article.rst',
+                                     DEFAULT_DATE='2012-05-01')
+
+        self.assertEqual(tuple_date.metadata['date'],
+                         string_date.metadata['date'])
+
 
 @unittest.skipUnless(readers.Markdown, "markdown isn't installed")
 class MdReaderTest(ReaderTest):