From d7e76405c7c1afe830faf40646b704be5c51ad51 Mon Sep 17 00:00:00 2001
From: Victor Stinner <victor.stinner@haypocalc.com>
Date: Tue, 22 Feb 2011 23:38:34 +0000
Subject: Issue #3080: document encoding used by import functions

---
 Include/import.h       | 59 ++++++++++++++++++++++++++++++++++++++------------
 Include/moduleobject.h |  4 +++-
 Include/pycapsule.h    |  4 +++-
 3 files changed, 51 insertions(+), 16 deletions(-)

diff --git a/Include/import.h b/Include/import.h
index 2df94ff..400e97c 100644
--- a/Include/import.h
+++ b/Include/import.h
@@ -9,26 +9,49 @@ extern "C" {
 
 PyAPI_FUNC(long) PyImport_GetMagicNumber(void);
 PyAPI_FUNC(const char *) PyImport_GetMagicTag(void);
-PyAPI_FUNC(PyObject *) PyImport_ExecCodeModule(char *name, PyObject *co);
+PyAPI_FUNC(PyObject *) PyImport_ExecCodeModule(
+    char *name,                 /* UTF-8 encoded string */
+    PyObject *co
+    );
 PyAPI_FUNC(PyObject *) PyImport_ExecCodeModuleEx(
-	char *name, PyObject *co, char *pathname);
+    char *name,                 /* UTF-8 encoded string */
+    PyObject *co,
+    char *pathname              /* decoded from the filesystem encoding */
+    );
 PyAPI_FUNC(PyObject *) PyImport_ExecCodeModuleWithPathnames(
-	char *name, PyObject *co, char *pathname, char *cpathname);
+    char *name,                 /* UTF-8 encoded string */
+    PyObject *co,
+    char *pathname,             /* decoded from the filesystem encoding */
+    char *cpathname             /* decoded from the filesystem encoding */
+    );
 PyAPI_FUNC(PyObject *) PyImport_GetModuleDict(void);
-PyAPI_FUNC(PyObject *) PyImport_AddModule(const char *name);
-PyAPI_FUNC(PyObject *) PyImport_ImportModule(const char *name);
-PyAPI_FUNC(PyObject *) PyImport_ImportModuleNoBlock(const char *);
-PyAPI_FUNC(PyObject *) PyImport_ImportModuleLevel(char *name,
-	PyObject *globals, PyObject *locals, PyObject *fromlist, int level);
+PyAPI_FUNC(PyObject *) PyImport_AddModule(
+    const char *name            /* UTF-8 encoded string */
+    );
+PyAPI_FUNC(PyObject *) PyImport_ImportModule(
+    const char *name            /* UTF-8 encoded string */
+    );
+PyAPI_FUNC(PyObject *) PyImport_ImportModuleNoBlock(
+    const char *name            /* UTF-8 encoded string */
+    );
+PyAPI_FUNC(PyObject *) PyImport_ImportModuleLevel(
+    char *name,                 /* UTF-8 encoded string */
+    PyObject *globals,
+    PyObject *locals,
+    PyObject *fromlist,
+    int level
+    );
 
 #define PyImport_ImportModuleEx(n, g, l, f) \
-	PyImport_ImportModuleLevel(n, g, l, f, -1)
+    PyImport_ImportModuleLevel(n, g, l, f, -1)
 
 PyAPI_FUNC(PyObject *) PyImport_GetImporter(PyObject *path);
 PyAPI_FUNC(PyObject *) PyImport_Import(PyObject *name);
 PyAPI_FUNC(PyObject *) PyImport_ReloadModule(PyObject *m);
 PyAPI_FUNC(void) PyImport_Cleanup(void);
-PyAPI_FUNC(int) PyImport_ImportFrozenModule(char *);
+PyAPI_FUNC(int) PyImport_ImportFrozenModule(
+    char *name                  /* UTF-8 encoded string */
+    );
 
 #ifndef Py_LIMITED_API
 #ifdef WITH_THREAD
@@ -41,9 +64,14 @@ PyAPI_FUNC(int) _PyImport_ReleaseLock(void);
 
 PyAPI_FUNC(void) _PyImport_ReInitLock(void);
 
-PyAPI_FUNC(PyObject *)_PyImport_FindBuiltin(char *);
+PyAPI_FUNC(PyObject *)_PyImport_FindBuiltin(
+    char *name                  /* UTF-8 encoded string */
+    );
 PyAPI_FUNC(PyObject *)_PyImport_FindExtensionUnicode(char *, PyObject *);
-PyAPI_FUNC(int)_PyImport_FixupBuiltin(PyObject*, char *);
+PyAPI_FUNC(int)_PyImport_FixupBuiltin(
+    PyObject *mod,
+    char *name                  /* UTF-8 encoded string */
+    );
 PyAPI_FUNC(int)_PyImport_FixupExtensionUnicode(PyObject*, char *, PyObject *);
 
 struct _inittab {
@@ -56,11 +84,14 @@ PyAPI_FUNC(int) PyImport_ExtendInittab(struct _inittab *newtab);
 
 PyAPI_DATA(PyTypeObject) PyNullImporter_Type;
 
-PyAPI_FUNC(int) PyImport_AppendInittab(const char *name, PyObject* (*initfunc)(void));
+PyAPI_FUNC(int) PyImport_AppendInittab(
+    const char *name,           /* ASCII encoded string */
+    PyObject* (*initfunc)(void)
+    );
 
 #ifndef Py_LIMITED_API
 struct _frozen {
-    char *name;
+    char *name;                 /* ASCII encoded string */
     unsigned char *code;
     int size;
 };
diff --git a/Include/moduleobject.h b/Include/moduleobject.h
index 338cf4b..7b2bf1c 100644
--- a/Include/moduleobject.h
+++ b/Include/moduleobject.h
@@ -12,7 +12,9 @@ PyAPI_DATA(PyTypeObject) PyModule_Type;
 #define PyModule_Check(op) PyObject_TypeCheck(op, &PyModule_Type)
 #define PyModule_CheckExact(op) (Py_TYPE(op) == &PyModule_Type)
 
-PyAPI_FUNC(PyObject *) PyModule_New(const char *);
+PyAPI_FUNC(PyObject *) PyModule_New(
+    const char *name            /* UTF-8 encoded string */
+    );
 PyAPI_FUNC(PyObject *) PyModule_GetDict(PyObject *);
 PyAPI_FUNC(const char *) PyModule_GetName(PyObject *);
 PyAPI_FUNC(const char *) PyModule_GetFilename(PyObject *);
diff --git a/Include/pycapsule.h b/Include/pycapsule.h
index eba82ee..d9ecda7 100644
--- a/Include/pycapsule.h
+++ b/Include/pycapsule.h
@@ -48,7 +48,9 @@ PyAPI_FUNC(int) PyCapsule_SetName(PyObject *capsule, const char *name);
 
 PyAPI_FUNC(int) PyCapsule_SetContext(PyObject *capsule, void *context);
 
-PyAPI_FUNC(void *) PyCapsule_Import(const char *name, int no_block);
+PyAPI_FUNC(void *) PyCapsule_Import(
+    const char *name,           /* UTF-8 encoded string */
+    int no_block);
 
 
 #ifdef __cplusplus
-- 
cgit v0.12