1

Can you tell me how I should formalize my .py file.

From some sources I've found that all files should start with:

# coding : utf-8
# PEP-8

Some people on GitHub do this:

# -*- coding: utf-8 -*-

However, Google for example doesn't use either of these and start files with license information:

# Copyright (C) 2018 Google Inc.
# Licensed under http://www.apache.org/licenses/LICENSE-2.0 <see LICENSE file>

What is the best and accepted way?

MAx Shvedov
  • 195
  • 5
  • 13
  • IIRC, the `# PEP-8` declaration is an "opt-in" used by one of the super-checker tools that run a slew of format checkers, linters, etc., on your code, to specify that this file should be run through the `pep8` checker and rejected if there are any warnings. If I'm remembering right, it's probably obsolete, as (a) `pep8` is deprecated in favor of `pycodestyle`, and (b) neither of the current up-to-date super-checkers seems to use this declaration so it's probably one of the two that are no longer maintained. – abarnert Jul 02 '18 at 18:39

1 Answers1

4

It depends.

Python 2 used ASCII as default encoding for source files.

Python 3's default is UTF-8.

So, if you intend to only support Python 3+ then you don't have to declare the utf-8 encoding as it is already the default.

If you intend to support Python 2 as well and you have non-ASCII string literals then you should declare an encoding.

If your text editor also needs a coding declaration (e.g., if your Unix locale is set to, say, Latin-1, but your code is UTF-8), Python's lenient syntax allows a single declaration to be used for both—e.g., # -*- coding: utf-8 -*- is recognized by both emacs and Python.

Some official information:

Python 3's docs about unicode support: https://docs.python.org/3/howto/unicode.html#python-s-unicode-support

PEP 263 that introduced the encoding declaration syntax: https://www.python.org/dev/peps/pep-0263/

PEP 3210 about changing the default encoding from ASCII to UTF-8 starting from Python 3.0: https://www.python.org/dev/peps/pep-3120/

abarnert
  • 354,177
  • 51
  • 601
  • 671
DeepSpace
  • 78,697
  • 11
  • 109
  • 154
  • It might also be worth adding links to [PEP 263](https://www.python.org/dev/peps/pep-0263/) and [PEP 3120](https://www.python.org/dev/peps/pep-3120/), and maybe explaining the difference between the different coding declaration styles (basically, sharing the coding declaration between Python and emacs and/or vi). – abarnert Jul 02 '18 at 18:23
  • Thanks, cool. How about PEP-8 line and licence? – MAx Shvedov Jul 02 '18 at 18:25
  • @abarnert, thanks, added some references – DeepSpace Jul 02 '18 at 18:28
  • @MAxShvedov I doubt you will find any PEP about that. It is up to personal preferences and organizational conventions. – DeepSpace Jul 02 '18 at 18:29
  • @DeepSpace I got it, thank you again. – MAx Shvedov Jul 02 '18 at 18:32
  • Minor change: UTF-8 is the encoding; Unicode is what's encoded. Also, added a paragraph that explains the funky syntax the OP is seeing (many people on GitHub use emacs, vi, or both, so they use a coding declaration that's shared with their editor). – abarnert Jul 02 '18 at 18:33
  • @abarnert Fair enough, thanks for the edit – DeepSpace Jul 02 '18 at 18:34
  • @MAxShvedov If you're publishing code under some license, you should read the license to see what it requires. But most of them don't require a comment per file, just one per repo (and if you let GitHub auto-generate a repo for you with a specific license, it will take care of that automatically). – abarnert Jul 02 '18 at 18:35