Rename cpu_count_physical() to cpu_count_cores()

This has always been cause of confusion, e.g. see:
https://github.com/giampaolo/psutil/pull/1727#issuecomment-698934643

Removed the reference to "physical" from dostrings, functions and test.
I still left it in the doc though, as it's more explanatory.

Signed-off-by: Giampaolo Rodola <g.rodola@gmail.com>

23 files changed, 68 insertions, 70 deletions

diff --git a/HISTORY.rst b/HISTORY.rst
index cf81ddc7..9f5281f9 100644
--- a/HISTORY.rst
+++ b/HISTORY.rst
@@ -59,8 +59,8 @@ XXXX-XX-XX
 
 **Bug fixes**
 
-- 1620_: [Linux] physical cpu_count() result is incorrect on systems with more
-  than one CPU socket.  (patch by Vincent A. Arcila)
+- 1620_: [Linux] cpu_count(logical=False) result is incorrect on systems with
+  more than one CPU socket.  (patch by Vincent A. Arcila)
 - 1738_: [macOS] Process.exe() may raise FileNotFoundError if process is still
   alive but the exe file which launched it got deleted.
 - 1791_: [macOS] fix missing include for getpagesize().
@@ -256,7 +256,7 @@ XXXX-XX-XX
   average calculation, including on Windows (emulated).  (patch by Ammar Askar)
 - 1404_: [Linux] cpu_count(logical=False) uses a second method (read from
   `/sys/devices/system/cpu/cpu[0-9]/topology/core_id`) in order to determine
-  the number of physical CPUs in case /proc/cpuinfo does not provide this info.
+  the number of CPU cores in case /proc/cpuinfo does not provide this info.
 - 1458_: provide coloured test output. Also show failures on KeyboardInterrupt.
 - 1464_: various docfixes (always point to python3 doc, fix links, etc.).
 - 1476_: [Windows] it is now possible to set process high I/O priority
@@ -502,7 +502,7 @@ XXXX-XX-XX
 - 694_: [SunOS] cmdline() could be truncated at the 15th character when
   reading it from /proc. An extra effort is made by reading it from process
   address space first.  (patch by Georg Sauthoff)
-- 771_: [Windows] cpu_count() (both logical and physical) return a wrong
+- 771_: [Windows] cpu_count() (both logical and cores) return a wrong
   (smaller) number on systems using process groups (> 64 cores).
 - 771_: [Windows] cpu_times(percpu=True) return fewer CPUs on systems using
   process groups (> 64 cores).
@@ -1306,8 +1306,8 @@ XXXX-XX-XX
 - 593_: [FreeBSD] Process().memory_maps() segfaults.
 - 606_: Process.parent() may swallow NoSuchProcess exceptions.
 - 611_: [SunOS] net_io_counters has send and received swapped
-- 614_: [Linux]: cpu_count(logical=False) return the number of physical CPUs
-  instead of physical cores.
+- 614_: [Linux]: cpu_count(logical=False) return the number of sockets instead
+  of cores.
 - 618_: [SunOS] swap tests fail on Solaris when run as normal user
 - 628_: [Linux] Process.name() truncates process name in case it contains
   spaces or parentheses.
@@ -1424,7 +1424,7 @@ XXXX-XX-XX
 **Enhancements**
 
 - 424_: [Windows] installer for Python 3.X 64 bit.
-- 427_: number of logical and physical CPUs (psutil.cpu_count()).
+- 427_: number of logical CPUs and physical cores (psutil.cpu_count()).
 - 447_: psutil.wait_procs() timeout parameter is now optional.
 - 452_: make Process instances hashable and usable with set()s.
 - 453_: tests on Python < 2.7 require unittest2 module.
diff --git a/docs/index.rst b/docs/index.rst
index 8c3b432b..d452c51c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -205,13 +205,13 @@ CPU
 
   Return the number of logical CPUs in the system (same as `os.cpu_count`_
   in Python 3.4) or ``None`` if undetermined.
-  *logical* cores means the number of physical cores multiplied by the number
+  "logical CPUs" means the number of physical cores multiplied by the number
   of threads that can run on each core (this is known as Hyper Threading).
-  If *logical* is ``False`` return the number of physical cores only (Hyper
-  Thread CPUs are excluded) or ``None`` if undetermined.
+  If *logical* is ``False`` return the number of physical cores only, or
+  ``None`` if undetermined.
   On OpenBSD and NetBSD ``psutil.cpu_count(logical=False)`` always return
   ``None``.
-  Example on a system having 2 physical hyper-thread CPU cores:
+  Example on a system having 2 cores + Hyper Threading:
 
     >>> import psutil
     >>> psutil.cpu_count()
@@ -219,11 +219,11 @@ CPU
     >>> psutil.cpu_count(logical=False)
     2
 
-  Note that this number is not equivalent to the number of CPUs the current
-  process can actually use.
+  Note that ``psutil.cpu_count()`` may not necessarily be equivalent to the
+  actual number of CPUs the current process can use.
   That can vary in case process CPU affinity has been changed, Linux cgroups
-  are being used or on Windows systems using processor groups or having more
-  than 64 CPUs.
+  are being used or (in case of Windows) on systems using processor groups or
+  having more than 64 CPUs.
   The number of usable CPUs can be obtained with:
 
     >>> len(psutil.Process().cpu_affinity())
diff --git a/psutil/__init__.py b/psutil/__init__.py
index 488eb694..44efb7ff 100644
--- a/psutil/__init__.py
+++ b/psutil/__init__.py
@@ -1575,7 +1575,7 @@ def cpu_count(logical=True):
     if logical:
         ret = _psplatform.cpu_count_logical()
     else:
-        ret = _psplatform.cpu_count_physical()
+        ret = _psplatform.cpu_count_cores()
     if ret is not None and ret < 1:
         ret = None
     return ret
diff --git a/psutil/_psaix.py b/psutil/_psaix.py
index 7160ecd6..3e3a3d14 100644
--- a/psutil/_psaix.py
+++ b/psutil/_psaix.py
@@ -143,7 +143,7 @@ def cpu_count_logical():
         return None
 
 
-def cpu_count_physical():
+def cpu_count_cores():
     cmd = "lsdev -Cc processor"
     p = subprocess.Popen(cmd, shell=True, stdout=subprocess.PIPE,
                          stderr=subprocess.PIPE)
diff --git a/psutil/_psbsd.py b/psutil/_psbsd.py
index 764463e9..1e47696a 100644
--- a/psutil/_psbsd.py
+++ b/psutil/_psbsd.py
@@ -249,19 +249,19 @@ def cpu_count_logical():
 
 
 if OPENBSD or NETBSD:
-    def cpu_count_physical():
+    def cpu_count_cores():
         # OpenBSD and NetBSD do not implement this.
         return 1 if cpu_count_logical() == 1 else None
 else:
-    def cpu_count_physical():
-        """Return the number of physical CPUs in the system."""
+    def cpu_count_cores():
+        """Return the number of CPU cores in the system."""
         # From the C module we'll get an XML string similar to this:
         # http://manpages.ubuntu.com/manpages/precise/man4/smp.4freebsd.html
         # We may get None in case "sysctl kern.sched.topology_spec"
         # is not supported on this BSD version, in which case we'll mimic
         # os.cpu_count() and return None.
         ret = None
-        s = cext.cpu_count_phys()
+        s = cext.cpu_count_cores()
         if s is not None:
             # get rid of padding chars appended at the end of the string
             index = s.rfind("</groups>")
@@ -274,8 +274,7 @@ else:
                     # needed otherwise it will memleak
                     root.clear()
         if not ret:
-            # If logical CPUs are 1 it's obvious we'll have only 1
-            # physical CPU.
+            # If logical CPUs == 1 it's obvious we' have only 1 core.
             if cpu_count_logical() == 1:
                 return 1
         return ret
diff --git a/psutil/_pslinux.py b/psutil/_pslinux.py
index be43f08b..39155745 100644
--- a/psutil/_pslinux.py
+++ b/psutil/_pslinux.py
@@ -656,8 +656,8 @@ def cpu_count_logical():
         return num
 
 
-def cpu_count_physical():
-    """Return the number of physical cores in the system."""
+def cpu_count_cores():
+    """Return the number of CPU cores in the system."""
     # Method #1
     ls = set()
     # These 2 files are the same but */core_cpus_list is newer while
diff --git a/psutil/_psosx.py b/psutil/_psosx.py
index c7770d65..d948cc15 100644
--- a/psutil/_psosx.py
+++ b/psutil/_psosx.py
@@ -159,9 +159,9 @@ def cpu_count_logical():
     return cext.cpu_count_logical()
 
 
-def cpu_count_physical():
-    """Return the number of physical CPUs in the system."""
-    return cext.cpu_count_phys()
+def cpu_count_cores():
+    """Return the number of CPU cores in the system."""
+    return cext.cpu_count_cores()
 
 
 def cpu_stats():
diff --git a/psutil/_pssunos.py b/psutil/_pssunos.py
index 5618bd44..816ebf07 100644
--- a/psutil/_pssunos.py
+++ b/psutil/_pssunos.py
@@ -190,9 +190,9 @@ def cpu_count_logical():
         return None
 
 
-def cpu_count_physical():
-    """Return the number of physical CPUs in the system."""
-    return cext.cpu_count_phys()
+def cpu_count_cores():
+    """Return the number of CPU cores in the system."""
+    return cext.cpu_count_cores()
 
 
 def cpu_stats():
diff --git a/psutil/_psutil_bsd.c b/psutil/_psutil_bsd.c
index 15b646e3..dc157e68 100644
--- a/psutil/_psutil_bsd.c
+++ b/psutil/_psutil_bsd.c
@@ -1096,8 +1096,8 @@ static PyMethodDef mod_methods[] = {
      "Get process resource limits."},
     {"proc_setrlimit", psutil_proc_setrlimit, METH_VARARGS,
      "Set process resource limits."},
-    {"cpu_count_phys", psutil_cpu_count_phys, METH_VARARGS,
-     "Return an XML string to determine the number physical CPUs."},
+    {"cpu_count_cores", psutil_cpu_count_cores, METH_VARARGS,
+     "Return an XML string to determine the number CPU cores."},
 #endif
     {"proc_environ", psutil_proc_environ, METH_VARARGS,
      "Return process environment"},
diff --git a/psutil/_psutil_osx.c b/psutil/_psutil_osx.c
index 5720de9f..b5aa7653 100644
--- a/psutil/_psutil_osx.c
+++ b/psutil/_psutil_osx.c
@@ -383,10 +383,10 @@ psutil_cpu_count_logical(PyObject *self, PyObject *args) {
 
 
 /*
- * Return the number of physical CPUs in the system.
+ * Return the number of CPU cores in the system.
  */
 static PyObject *
-psutil_cpu_count_phys(PyObject *self, PyObject *args) {
+psutil_cpu_count_cores(PyObject *self, PyObject *args) {
     int num;
     size_t size = sizeof(int);
 
@@ -1789,8 +1789,8 @@ static PyMethodDef mod_methods[] = {
      "Returns a list of PIDs currently running on the system"},
     {"cpu_count_logical", psutil_cpu_count_logical, METH_VARARGS,
      "Return number of logical CPUs on the system"},
-    {"cpu_count_phys", psutil_cpu_count_phys, METH_VARARGS,
-     "Return number of physical CPUs on the system"},
+    {"cpu_count_cores", psutil_cpu_count_cores, METH_VARARGS,
+     "Return number of CPU cores on the system"},
     {"virtual_mem", psutil_virtual_mem, METH_VARARGS,
      "Return system virtual memory stats"},
     {"swap_mem", psutil_swap_mem, METH_VARARGS,
diff --git a/psutil/_psutil_sunos.c b/psutil/_psutil_sunos.c
index 82114c8c..342798a8 100644
--- a/psutil/_psutil_sunos.c
+++ b/psutil/_psutil_sunos.c
@@ -1437,10 +1437,10 @@ psutil_boot_time(PyObject *self, PyObject *args) {
 
 
 /*
- * Return the number of physical CPU cores on the system.
+ * Return the number of CPU cores on the system.
  */
 static PyObject *
-psutil_cpu_count_phys(PyObject *self, PyObject *args) {
+psutil_cpu_count_cores(PyObject *self, PyObject *args) {
     kstat_ctl_t *kc;
     kstat_t *ksp;
     int ncpus = 0;
@@ -1669,8 +1669,8 @@ PsutilMethods[] = {
      "Return a Python dict of tuples for network I/O statistics."},
     {"boot_time", psutil_boot_time, METH_VARARGS,
      "Return system boot time in seconds since the EPOCH."},
-    {"cpu_count_phys", psutil_cpu_count_phys, METH_VARARGS,
-     "Return the number of physical CPUs on the system."},
+    {"cpu_count_cores", psutil_cpu_count_cores, METH_VARARGS,
+     "Return the number of CPU cores on the system."},
     {"net_connections", psutil_net_connections, METH_VARARGS,
      "Return TCP and UDP syste-wide open connections."},
     {"net_if_stats", psutil_net_if_stats, METH_VARARGS,
diff --git a/psutil/_psutil_windows.c b/psutil/_psutil_windows.c
index a2154e92..93a659bf 100644
--- a/psutil/_psutil_windows.c
+++ b/psutil/_psutil_windows.c
@@ -1611,8 +1611,8 @@ PsutilMethods[] = {
      "Determine if the process exists in the current process list."},
     {"cpu_count_logical", psutil_cpu_count_logical, METH_VARARGS,
      "Returns the number of logical CPUs on the system"},
-    {"cpu_count_phys", psutil_cpu_count_phys, METH_VARARGS,
-     "Returns the number of physical CPUs on the system"},
+    {"cpu_count_cores", psutil_cpu_count_cores, METH_VARARGS,
+     "Returns the number of CPU cores on the system"},
     {"boot_time", psutil_boot_time, METH_VARARGS,
      "Return the system boot time expressed in seconds since the epoch."},
     {"virtual_mem", psutil_virtual_mem, METH_VARARGS,
diff --git a/psutil/_pswindows.py b/psutil/_pswindows.py
index 98baef59..138bc83d 100644
--- a/psutil/_pswindows.py
+++ b/psutil/_pswindows.py
@@ -304,9 +304,9 @@ def cpu_count_logical():
     return cext.cpu_count_logical()
 
 
-def cpu_count_physical():
-    """Return the number of physical CPU cores in the system."""
-    return cext.cpu_count_phys()
+def cpu_count_cores():
+    """Return the number of CPU cores in the system."""
+    return cext.cpu_count_cores()
 
 
 def cpu_stats():
diff --git a/psutil/arch/freebsd/specific.c b/psutil/arch/freebsd/specific.c
index 2776de8c..748089cf 100644
--- a/psutil/arch/freebsd/specific.c
+++ b/psutil/arch/freebsd/specific.c
@@ -364,9 +364,9 @@ error:
 
 
 PyObject *
-psutil_cpu_count_phys(PyObject *self, PyObject *args) {
+psutil_cpu_count_cores(PyObject *self, PyObject *args) {
     // Return an XML string from which we'll determine the number of
-    // physical CPU cores in the system.
+    // CPU cores in the system.
     void *topology = NULL;
     size_t size = 0;
     PyObject *py_str;
diff --git a/psutil/arch/freebsd/specific.h b/psutil/arch/freebsd/specific.h
index 61c3f07b..c579cff7 100644
--- a/psutil/arch/freebsd/specific.h
+++ b/psutil/arch/freebsd/specific.h
@@ -12,7 +12,7 @@ int psutil_get_proc_list(struct kinfo_proc **procList, size_t *procCount);
 int psutil_kinfo_proc(const pid_t pid, struct kinfo_proc *proc);
 
 //
-PyObject* psutil_cpu_count_phys(PyObject* self, PyObject* args);
+PyObject* psutil_cpu_count_cores(PyObject* self, PyObject* args);
 PyObject* psutil_disk_io_counters(PyObject* self, PyObject* args);
 PyObject* psutil_get_cmdline(long pid);
 PyObject* psutil_per_cpu_times(PyObject* self, PyObject* args);
diff --git a/psutil/arch/windows/cpu.c b/psutil/arch/windows/cpu.c
index 18f32e59..355de6df 100644
--- a/psutil/arch/windows/cpu.c
+++ b/psutil/arch/windows/cpu.c
@@ -177,11 +177,10 @@ psutil_cpu_count_logical(PyObject *self, PyObject *args) {
 
 
 /*
- * Return the number of physical CPU cores (hyper-thread CPUs count
- * is excluded).
+ * Return the number of CPU cores (non hyper-threading).
  */
 PyObject *
-psutil_cpu_count_phys(PyObject *self, PyObject *args) {
+psutil_cpu_count_cores(PyObject *self, PyObject *args) {
     DWORD rc;
     PSYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX buffer = NULL;
     PSYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX ptr = NULL;
@@ -196,7 +195,7 @@ psutil_cpu_count_phys(PyObject *self, PyObject *args) {
     // than 64 CPUs. See:
     // https://bugs.python.org/issue33166
     if (GetLogicalProcessorInformationEx == NULL) {
-        psutil_debug("Win < 7; cpu_count_phys() forced to None");
+        psutil_debug("Win < 7; cpu_count_cores() forced to None");
         Py_RETURN_NONE;
     }
 
diff --git a/psutil/arch/windows/cpu.h b/psutil/arch/windows/cpu.h
index d88c2212..1ef3ff1f 100644
--- a/psutil/arch/windows/cpu.h
+++ b/psutil/arch/windows/cpu.h
@@ -7,7 +7,7 @@
 #include <Python.h>
 
 PyObject *psutil_cpu_count_logical(PyObject *self, PyObject *args);
-PyObject *psutil_cpu_count_phys(PyObject *self, PyObject *args);
+PyObject *psutil_cpu_count_cores(PyObject *self, PyObject *args);
 PyObject *psutil_cpu_freq(PyObject *self, PyObject *args);
 PyObject *psutil_cpu_stats(PyObject *self, PyObject *args);
 PyObject *psutil_cpu_times(PyObject *self, PyObject *args);
diff --git a/psutil/arch/windows/ntextapi.h b/psutil/arch/windows/ntextapi.h
index ea1f4281..e0662fa0 100644
--- a/psutil/arch/windows/ntextapi.h
+++ b/psutil/arch/windows/ntextapi.h
@@ -399,7 +399,7 @@ typedef struct _WTSINFOW {
 
 #define PWTSINFO PWTSINFOW
 
-// cpu_count_phys()
+// cpu_count_cores()
 #if (_WIN32_WINNT < 0x0601)  // Windows < 7 (Vista and XP)
 typedef struct _SYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX {
     LOGICAL_PROCESSOR_RELATIONSHIP Relationship;
diff --git a/psutil/tests/test_linux.py b/psutil/tests/test_linux.py
index f8a9e008..2f6065f5 100755
--- a/psutil/tests/test_linux.py
+++ b/psutil/tests/test_linux.py
@@ -715,7 +715,7 @@ class TestSystemCPUCountLogical(PsutilTestCase):
 
 
 @unittest.skipIf(not LINUX, "LINUX only")
-class TestSystemCPUCountPhysical(PsutilTestCase):
+class TestSystemCPUCountCores(PsutilTestCase):
 
     @unittest.skipIf(not which("lscpu"), "lscpu utility not available")
     def test_against_lscpu(self):
@@ -728,9 +728,9 @@ class TestSystemCPUCountPhysical(PsutilTestCase):
         self.assertEqual(psutil.cpu_count(logical=False), len(core_ids))
 
     def test_method_2(self):
-        meth_1 = psutil._pslinux.cpu_count_physical()
+        meth_1 = psutil._pslinux.cpu_count_cores()
         with mock.patch('glob.glob', return_value=[]) as m:
-            meth_2 = psutil._pslinux.cpu_count_physical()
+            meth_2 = psutil._pslinux.cpu_count_cores()
             assert m.called
         if meth_1 is not None:
             self.assertEqual(meth_1, meth_2)
@@ -738,7 +738,7 @@ class TestSystemCPUCountPhysical(PsutilTestCase):
     def test_emulate_none(self):
         with mock.patch('glob.glob', return_value=[]) as m1:
             with mock.patch('psutil._common.open', create=True) as m2:
-                self.assertIsNone(psutil._pslinux.cpu_count_physical())
+                self.assertIsNone(psutil._pslinux.cpu_count_cores())
         assert m1.called
         assert m2.called
 
diff --git a/psutil/tests/test_memleaks.py b/psutil/tests/test_memleaks.py
index ab6aac69..e6940a30 100755
--- a/psutil/tests/test_memleaks.py
+++ b/psutil/tests/test_memleaks.py
@@ -347,7 +347,7 @@ class TestModuleFunctionsLeaks(TestMemoryLeak):
         self.execute(lambda: psutil.cpu_count(logical=True))
 
     @fewtimes_if_linux()
-    def test_cpu_count_physical(self):
+    def test_cpu_count_cores(self):
         self.execute(lambda: psutil.cpu_count(logical=False))
 
     @fewtimes_if_linux()
diff --git a/psutil/tests/test_osx.py b/psutil/tests/test_osx.py
index 348976f8..b7a0b088 100755
--- a/psutil/tests/test_osx.py
+++ b/psutil/tests/test_osx.py
@@ -137,7 +137,7 @@ class TestSystemAPIs(PsutilTestCase):
         num = sysctl("sysctl hw.logicalcpu")
         self.assertEqual(num, psutil.cpu_count(logical=True))
 
-    def test_cpu_count_physical(self):
+    def test_cpu_count_cores(self):
         num = sysctl("sysctl hw.physicalcpu")
         self.assertEqual(num, psutil.cpu_count(logical=False))
 
diff --git a/psutil/tests/test_system.py b/psutil/tests/test_system.py
index 90ecff94..4e3ac3e4 100755
--- a/psutil/tests/test_system.py
+++ b/psutil/tests/test_system.py
@@ -316,16 +316,16 @@ class TestCpuAPIs(PsutilTestCase):
             if "physical id" not in cpuinfo_data:
                 raise unittest.SkipTest("cpuinfo doesn't include physical id")
 
-    def test_cpu_count_physical(self):
+    def test_cpu_count_cores(self):
         logical = psutil.cpu_count()
-        physical = psutil.cpu_count(logical=False)
-        if physical is None:
-            raise self.skipTest("physical cpu_count() is None")
+        cores = psutil.cpu_count(logical=False)
+        if cores is None:
+            raise self.skipTest("cpu_count_cores() is None")
         if WINDOWS and sys.getwindowsversion()[:2] <= (6, 1):  # <= Vista
-            self.assertIsNone(physical)
+            self.assertIsNone(cores)
         else:
-            self.assertGreaterEqual(physical, 1)
-            self.assertGreaterEqual(logical, physical)
+            self.assertGreaterEqual(cores, 1)
+            self.assertGreaterEqual(logical, cores)
 
     def test_cpu_count_none(self):
         # https://github.com/giampaolo/psutil/issues/1085
@@ -334,7 +334,7 @@ class TestCpuAPIs(PsutilTestCase):
                             return_value=val) as m:
                 self.assertIsNone(psutil.cpu_count())
                 assert m.called
-            with mock.patch('psutil._psplatform.cpu_count_physical',
+            with mock.patch('psutil._psplatform.cpu_count_cores',
                             return_value=val) as m:
                 self.assertIsNone(psutil.cpu_count(logical=False))
                 assert m.called
diff --git a/psutil/tests/test_windows.py b/psutil/tests/test_windows.py
index a9254e2c..aeb282c8 100755
--- a/psutil/tests/test_windows.py
+++ b/psutil/tests/test_windows.py
@@ -100,7 +100,7 @@ class TestCpuAPIs(WindowsTestCase):
         proc = w.Win32_Processor()[0]
         self.assertEqual(psutil.cpu_count(), proc.NumberOfLogicalProcessors)
 
-    def test_cpu_count_phys_vs_wmi(self):
+    def test_cpu_count_cores_vs_wmi(self):
         w = wmi.WMI()
         proc = w.Win32_Processor()[0]
         self.assertEqual(psutil.cpu_count(logical=False), proc.NumberOfCores)